Menubar
Organizes and presents a collection of menu options or actions within a horizontal bar.
Structure
Reusable Components
If you're planning to use Menubar in multiple places, you can create reusable components that wrap the different parts of the Menubar.
In the following example, we're creating a reusable MyMenubarMenu
component that contains the trigger, content, and items of a menu.
Now, we can use the MyMenubarMenu
component within a Menubar.Root
component to render out the various menus.
Managing Value State
Bits UI provides flexible options for controlling and synchronizing the menubar's active value state. The value
represents the currently opened menu within the menubar.
Two-Way Binding
Use the bind:value
directive for effortless two-way synchronization between your local state and the menubar's internal state.
Change Handler
You can also use the onValueCHange
prop to update local state when the menubar's active menu changes. This is useful when you don't want two-way binding for one reason or another, or you want to perform additional logic when the menus open or close.
Checkbox Items
You can use the Menubar.CheckboxItem
component to create a menuitemcheckbox
element to add checkbox functionality to menu items.
Radio Groups
You can combine the Menubar.RadioGroup
and Menubar.RadioItem
components to create a radio group within a menu.
Nested Menus
You can create nested menus using the Menubar.Sub
component to create complex menu structures.
Svelte Transitions
You can use the forceMount
prop along with the child
snippet to forcefully mount the Menubar.Content
component to use Svelte Transitions or another animation library that requires more control.
Of course, this isn't the prettiest syntax, so it's recommended to create your own reusable content component that handles this logic if you intend to use this approach. For more information on using transitions with Bits UI components, see the Transitions documentation.
API Reference
The root menubar component which manages & scopes the state of the menubar.
Property | Type | Description |
---|---|---|
value bindable prop | string | The value of the currently active menu. Default: undefined |
onValueChange | function | A callback function called when the active menu value changes. Default: undefined |
dir | enum | The reading direction of the app. Default: ltr |
loop | boolean | Whether or not to loop through the menubar menu triggers when navigating with the keyboard. Default: true |
ref bindable prop | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
A menu within the menubar.
Property | Type | Description |
---|---|---|
value | string | The value of this menu within the menubar, used to identify it when determining which menu is active. Default: undefined |
open bindable prop | boolean | The open state of the menu. Default: false |
onOpenChange | function | A callback that is fired when the menu's open state changes. Default: undefined |
dir | enum | The reading direction of the app. Default: ltr |
children | Snippet | The children content to render. Default: undefined |
The button element which toggles the dropdown menu.
Property | Type | Description |
---|---|---|
disabled | boolean | Whether or not the menu trigger is disabled. Default: false |
ref bindable prop | HTMLButtonElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-state | enum | The open state of the menu or submenu the element controls or belongs to. |
data-menu-trigger | '' | Present on the trigger element. |
A component that portals the content of the dropdown menu to the body or a custom target (if provided).
Property | Type | Description |
---|---|---|
to | union | Where to render the content when it is open. Defaults to the body. Can be disabled by passing Default: body |
disabled | boolean | Whether the portal is disabled or not. When disabled, the content will be rendered in its original DOM location. Default: false |
children | Snippet | The children content to render. Default: undefined |
The content displayed when the dropdown menu is open.
Property | Type | Description |
---|---|---|
side | enum | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur. Default: bottom |
sideOffset | number | The distance in pixels from the anchor to the floating element. Default: 0 |
align | enum | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur. Default: start |
alignOffset | number | The distance in pixels from the anchor to the floating element. Default: 0 |
arrowPadding | number | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision. Default: 0 |
avoidCollisions | boolean | When Default: true |
collisionBoundary | union | A boundary element or array of elements to check for collisions against. Default: undefined |
collisionPadding | union | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision. Default: 0 |
sticky | enum | The sticky behavior on the align axis. Default: partial |
hideWhenDetached | boolean | When Default: true |
updatePositionStrategy | enum | The strategy to use when updating the position of the content. When Default: optimized |
strategy | enum | The positioning strategy to use for the floating element. When Default: fixed |
preventScroll | boolean | When Default: true |
onEscapeKeydown | function | Callback fired when an escape keydown event occurs in the floating content. You can call Default: undefined |
escapeKeydownBehavior | enum | The behavior to use when an escape keydown event occurs in the floating content. Default: close |
onInteractOutside | function | Callback fired when an outside interaction event completes, which is either a Default: undefined |
onInteractOutsideStart | function | Callback fired when an outside interaction event starts, which is either a Default: undefined |
onFocusOutside | function | Callback fired when focus leaves the dismissable layer. You can call Default: undefined |
interactOutsideBehavior | enum | The behavior to use when an interaction occurs outside of the floating content. Default: close |
onMountAutoFocus | function | Event handler called when auto-focusing the content as it is mounted. Can be prevented. Default: undefined |
onDestroyAutoFocus | function | Event handler called when auto-focusing the content as it is destroyed. Can be prevented. Default: undefined |
trapFocus | boolean | Whether or not to trap the focus within the content when open. Default: true |
forceMount | boolean | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content. Default: false |
preventOverflowTextSelection | boolean | When Default: true |
dir | enum | The reading direction of the app. Default: ltr |
loop | boolean | Whether or not to loop through the menu items in when navigating with the keyboard. Default: false |
ref bindable prop | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-state | enum | The open state of the menu or submenu the element controls or belongs to. |
data-menu-content | '' | Present on the content element. |
A menu item within the dropdown menu.
Property | Type | Description |
---|---|---|
disabled | boolean | Whether or not the menu item is disabled. Default: false |
textValue | string | The text value of the checkbox menu item. This is used for typeahead. Default: undefined |
onSelect | function | A callback that is fired when the menu item is selected. Default: undefined |
ref bindable prop | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-orientation | 'vertical' | |
data-highlighted | '' | Present when the menu item is highlighted. |
data-disabled | '' | Present when the menu item is disabled. |
data-menu-item | '' | Present on the item element. |
A menu item that can be controlled and toggled like a checkbox.
Property | Type | Description |
---|---|---|
disabled | boolean | Whether or not the checkbox menu item is disabled. Disabled items cannot be interacted with and are skipped when navigating with the keyboard. Default: false |
checked bindable prop | union | The checkbox menu item's checked state. Default: false |
onCheckedChange | function | A callback that is fired when the checkbox menu item's checked state changes. Default: undefined |
textValue | string | The text value of the checkbox menu item. This is used for typeahead. Default: undefined |
onSelect | function | A callback that is fired when the menu item is selected. Default: undefined |
ref bindable prop | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-orientation | 'vertical' | |
data-highlighted | '' | Present when the menu item is highlighted. |
data-disabled | '' | Present when the menu item is disabled. |
data-state | enum | The checkbox menu item's checked state. |
A group of radio menu items, where only one can be checked at a time.
Property | Type | Description |
---|---|---|
value bindable prop | string | The value of the currently checked radio menu item. Default: undefined |
onValueChange | function | A callback that is fired when the radio group's value changes. Default: undefined |
ref bindable prop | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-menu-radio-group | '' | Present on the radio group element. |
A menu item that can be controlled and toggled like a radio button. It must be a child of a RadioGroup
.
Property | Type | Description |
---|---|---|
value required prop | string | The value of the radio item. When checked, the parent Default: undefined |
disabled | boolean | Whether or not the radio menu item is disabled. Disabled items cannot be interacted with and are skipped when navigating with the keyboard. Default: false |
textValue | string | The text value of the checkbox menu item. This is used for typeahead. Default: undefined |
onSelect | function | A callback that is fired when the menu item is selected. Default: undefined |
ref bindable prop | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-orientation | 'vertical' | |
data-highlighted | '' | Present when the menu item is highlighted. |
data-disabled | '' | Present when the menu item is disabled. |
data-state | enum | The radio menu item's checked state. |
data-value | '' | The value of the radio item. |
data-menu-radio-item | '' | Present on the radio item element. |
A horizontal line to visually separate menu items.
Property | Type | Description |
---|---|---|
ref bindable prop | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-orientation | 'vertical' | The orientation of the separator. |
data-menu-separator | '' | Present on the separator element. |
An optional arrow which points to the dropdown menu's anchor/trigger point.
Property | Type | Description |
---|---|---|
width | number | The width of the arrow in pixels. Default: 8 |
height | number | The height of the arrow in pixels. Default: 8 |
ref bindable prop | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-state | enum | The open state of the menu or submenu the element controls or belongs to. |
data-menu-arrow | '' | Present on the arrow element. |
A group of menu items. It should be passed an aria-label
or have a child Menu.GroupLabel
component to provide a label for a group of menu items.
Property | Type | Description |
---|---|---|
ref bindable prop | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-menu-group | '' | Present on the group element. |
A label which will be skipped when navigating with the keyboard. It is used to provide a label for a group of menu items and must be a child of either a Menubar.Group
or Menubar.RadioGroup
component.
Property | Type | Description |
---|---|---|
ref bindable prop | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-menu-label | '' | Present on the group label element. |
A submenu belonging to the parent dropdown menu. Responsible for managing the state of the submenu.
Property | Type | Description |
---|---|---|
open bindable prop | boolean | The open state of the submenu. Default: false |
onOpenChange | function | A callback that is fired when the submenu's open state changes. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
A menu item which when pressed or hovered, opens the submenu it is a child of.
Property | Type | Description |
---|---|---|
disabled | boolean | Whether or not the submenu trigger is disabled. Default: false |
textValue | string | The text value of the checkbox menu item. This is used for typeahead. Default: undefined |
onSelect | function | A callback that is fired when the menu item is selected. Default: undefined |
ref bindable prop | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-orientation | 'vertical' | |
data-highlighted | '' | Present when the menu item is highlighted. |
data-disabled | '' | Present when the menu item is disabled. |
data-state | enum | The open state of the menu or submenu the element controls or belongs to. |
data-menu-subtrigger | '' | Present on the submenu trigger element. |
The submenu content displayed when the parent submenu is open.
Property | Type | Description |
---|---|---|
side | enum | The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur. Default: bottom |
sideOffset | number | The distance in pixels from the anchor to the floating element. Default: 0 |
align | enum | The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur. Default: start |
alignOffset | number | The distance in pixels from the anchor to the floating element. Default: 0 |
arrowPadding | number | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision. Default: 0 |
avoidCollisions | boolean | When Default: true |
collisionBoundary | union | A boundary element or array of elements to check for collisions against. Default: undefined |
collisionPadding | union | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision. Default: 0 |
sticky | enum | The sticky behavior on the align axis. Default: partial |
hideWhenDetached | boolean | When Default: true |
updatePositionStrategy | enum | The strategy to use when updating the position of the content. When Default: optimized |
strategy | enum | The positioning strategy to use for the floating element. When Default: fixed |
preventScroll | boolean | When Default: true |
onEscapeKeydown | function | Callback fired when an escape keydown event occurs in the floating content. You can call Default: undefined |
escapeKeydownBehavior | enum | The behavior to use when an escape keydown event occurs in the floating content. Default: close |
onInteractOutside | function | Callback fired when an outside interaction event completes, which is either a Default: undefined |
onInteractOutsideStart | function | Callback fired when an outside interaction event starts, which is either a Default: undefined |
onFocusOutside | function | Callback fired when focus leaves the dismissable layer. You can call Default: undefined |
interactOutsideBehavior | enum | The behavior to use when an interaction occurs outside of the floating content. Default: close |
onMountAutoFocus | function | Event handler called when auto-focusing the content as it is mounted. Can be prevented. Default: undefined |
onDestroyAutoFocus | function | Event handler called when auto-focusing the content as it is destroyed. Can be prevented. Default: undefined |
trapFocus | boolean | Whether or not to trap the focus within the content when open. Default: true |
forceMount | boolean | Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content. Default: false |
preventOverflowTextSelection | boolean | When Default: true |
dir | enum | The reading direction of the app. Default: ltr |
loop | boolean | Whether or not to loop through the menu items in when navigating with the keyboard. Default: false |
ref bindable prop | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-state | enum | The open state of the menu or submenu the element controls or belongs to. |
data-menu-subcontent | '' | Present on the submenu content element. |