Kobalte.v0.13.1

Menubar

A visually persistent menu common in desktop applications that provides quick access to a consistent set of commands.

Import

ts
import { Menubar } from "@kobalte/core/menubar";
// or
import { Root, Menu, ... } from "@kobalte/core/menubar";
// or (deprecated)
import { Menubar } from "@kobalte/core";
ts
import { Menubar } from "@kobalte/core/menubar";
// or
import { Root, Menu, ... } from "@kobalte/core/menubar";
// or (deprecated)
import { Menubar } from "@kobalte/core";

Features

  • Follows the WAI ARIA Menubar design pattern.
  • Supports modal and non-modal modes.
  • Supports submenus.
  • Supports items, labels, groups of items.
  • Supports checkable items (single or multiple) with optional indeterminate state.
  • Support disabled items.
  • Complex item labeling support for accessibility.
  • Keyboard opening and navigation support.
  • Automatic scrolling support during keyboard navigation.
  • Typeahead to allow focusing items by typing text.
  • Optionally render a pointing arrow.
  • Focus is fully managed.

Anatomy

The context menu consists of:

  • Menubar: The root container for a menubar.
  • Menubar.Menu: The container of each menu.
  • Menubar.Trigger: The button that toggles the menu.
  • Menubar.Icon: A small icon that can be displayed inside the menu trigger as a visual affordance for the fact it can be open.
  • Menubar.Portal: Portals its children into the body when the menu is open.
  • Menubar.Content: Contains the content to be rendered when the menu is open.
  • Menubar.Arrow: An optional arrow element to render alongside the menu content.
  • Menubar.Separator: Used to visually separate items in the menu.
  • Menubar.Group: Used to group multiple items. Use in conjunction with Menubar.GroupLabel to ensure good accessibility via automatic labelling.
  • Menubar.GroupLabel: Used to render the label of a group. It won't be focusable using arrow keys.
  • Menubar.Sub: Contains all the parts of a submenu.
  • Menubar.SubTrigger: An item that opens a submenu. Must be rendered inside Menubar.Sub.
  • Menubar.SubContent: The component that pops out when a submenu is open. Must be rendered inside Menubar.Sub.

The menu item consists of:

  • Menubar.Item: An item of the select.
  • Menubar.ItemLabel: An accessible label to be announced for the item.
  • Menubar.ItemDescription: An optional accessible description to be announced for the item.
  • Menubar.ItemIndicator: The visual indicator rendered when the item is checked.

The checkable menu item consists of:

  • Menubar.RadioGroup: Used to group multiple Menubar.RadioItems and manage the selection.
  • Menubar.RadioItem: An item that can be controlled and rendered like a radio.
  • Menubar.CheckboxItem: An item that can be controlled and rendered like a checkbox.
tsx
<Menubar>
<Menubar.Menu>
<Menubar.Trigger>
<Menubar.Icon />
</Menubar.Trigger>
<Menubar.Portal>
<Menubar.Content>
<Menubar.Arrow />
<Menubar.Item>
<Menubar.ItemLabel />
<Menubar.ItemDescription />
</Menubar.Item>
<Menubar.Group>
<Menubar.GroupLabel />
<Menubar.Item />
</Menubar.Group>
<Menubar.CheckboxItem>
<Menubar.ItemIndicator />
</Menubar.CheckboxItem>
<Menubar.RadioGroup>
<Menubar.RadioItem>
<Menubar.ItemIndicator />
</Menubar.RadioItem>
</Menubar.RadioGroup>
<Menubar.Sub>
<Menubar.SubTrigger />
<Menubar.Portal>
<Menubar.SubContent />
</Menubar.Portal>
</Menubar.Sub>
<Menubar.Separator />
</Menubar.Content>
</Menubar.Portal>
</Menubar.Menu>
</Menubar>
tsx
<Menubar>
<Menubar.Menu>
<Menubar.Trigger>
<Menubar.Icon />
</Menubar.Trigger>
<Menubar.Portal>
<Menubar.Content>
<Menubar.Arrow />
<Menubar.Item>
<Menubar.ItemLabel />
<Menubar.ItemDescription />
</Menubar.Item>
<Menubar.Group>
<Menubar.GroupLabel />
<Menubar.Item />
</Menubar.Group>
<Menubar.CheckboxItem>
<Menubar.ItemIndicator />
</Menubar.CheckboxItem>
<Menubar.RadioGroup>
<Menubar.RadioItem>
<Menubar.ItemIndicator />
</Menubar.RadioItem>
</Menubar.RadioGroup>
<Menubar.Sub>
<Menubar.SubTrigger />
<Menubar.Portal>
<Menubar.SubContent />
</Menubar.Portal>
</Menubar.Sub>
<Menubar.Separator />
</Menubar.Content>
</Menubar.Portal>
</Menubar.Menu>
</Menubar>

Example

Usage

Origin-aware animations

We expose a CSS custom property --kb-popper-content-transform-origin which can be used to animate the content from its computed origin.

css
/* style.css */
.context-menu__content,
.context-menu__sub-content {
transform-origin: var(--kb-menu-content-transform-origin);
animation: contentHide 250ms ease-in forwards;
}
.context-menu__content[data-expanded],
.context-menu__sub-content[data-expanded] {
animation: contentShow 250ms ease-out;
}
@keyframes contentShow {
from {
opacity: 0;
transform: scale(0.96);
}
to {
opacity: 1;
transform: scale(1);
}
}
@keyframes contentHide {
from {
opacity: 1;
transform: scale(1);
}
to {
opacity: 0;
transform: scale(0.96);
}
}
css
/* style.css */
.context-menu__content,
.context-menu__sub-content {
transform-origin: var(--kb-menu-content-transform-origin);
animation: contentHide 250ms ease-in forwards;
}
.context-menu__content[data-expanded],
.context-menu__sub-content[data-expanded] {
animation: contentShow 250ms ease-out;
}
@keyframes contentShow {
from {
opacity: 0;
transform: scale(0.96);
}
to {
opacity: 1;
transform: scale(1);
}
}
@keyframes contentHide {
from {
opacity: 1;
transform: scale(1);
}
to {
opacity: 0;
transform: scale(0.96);
}
}

API Reference

Menubar is equivalent to the Root import from @kobalte/core/menubar (and deprecated Menubar.Root).

PropDescription
defaultValuestring
The value of the menu that should be open when initially rendered. Use when you do not need to control the value state.
valuestring
The controlled value of the menu to open. Should be used in conjunction with onValueChange.
onValueChange(value: string | undefined) => void
Event handler called when the value changes.
loopboolean
When true, keyboard navigation will loop from last item to first, and vice versa.
focusOnAltboolean
When true, click on alt by itsef will focus this Menubar (some browsers interfere)
PropDescription
onOpenChange(open: boolean) => void
Event handler called when the open state of the menu changes.
idstring
A unique identifier for the component. The id is used to generate id attributes for nested components. If no id prop is provided, a generated id will be used.
modalboolean
Whether the menu should be the only visible content for screen readers, when set to true:
- interaction with outside elements will be disabled.
- scroll will be locked.
- focus will be locked inside the menu content.
- elements outside the menu content will not be visible for screen readers.
preventScrollboolean
Whether the scroll should be locked even if the menu is not modal.
forceMountboolean
Used to force mounting the menu (portal and content) when more control is needed. Useful when controlling animation with SolidJS animation libraries.
valuestring
A unique value that associates the item with an active value when the navigation menu is controlled. This prop is managed automatically when uncontrolled.

Menubar.Menu also accepts the following props to customize the placement of the Menubar.Content.

PropDescription
placementPlacement
The placement of the menu content.
gutternumber
The distance between the menu content and the trigger element. By default, it's 0 plus half of the arrow offset, if it exists.
shiftnumber
The skidding of the menu content along the trigger element.
flipboolean | string
Controls the behavior of the menu content when it overflows the viewport:
- If a boolean, specifies whether the menu content should flip to the opposite side when it overflows.
- If a string, indicates the preferred fallback placements when it overflows.
The placements must be spaced-delimited, e.g. "top left".
slideboolean
Whether the menu content should slide when it overflows.
overlapboolean
Whether the menu content can overlap the trigger element when it overflows.
sameWidthboolean
Whether the menu content should have the same width as the trigger element. This will be exposed to CSS as --kb-popper-anchor-width.
fitViewportboolean
Whether the menu content should fit the viewport. If this is set to true, the menu content will have maxWidth and maxHeight set to the viewport size. This will be exposed to CSS as --kb-popper-available-width and --kb-popper-available-height.
hideWhenDetachedboolean
Whether to hide the menu content when the trigger element becomes occluded.
detachedPaddingnumber
The minimum padding in order to consider the trigger element occluded.
arrowPaddingnumber
The minimum padding between the arrow and the menu content corner.
overflowPaddingnumber
The minimum padding between the menu content and the viewport edge. This will be exposed to CSS as --kb-popper-overflow-padding.
PropDescription
disabledboolean
Whether the context menu trigger is disabled or not.
Data attributeDescription
data-expandedPresent when the menu is open.
data-closedPresent when the menu is close.
data-disabledPresent when the trigger is disabled.

Menubar.Icon, Menubar.Content, Menubar.SubTrigger and Menubar.SubContent share the same data-expanded attribute.

The popper positioner will copy the same z-index as the Menubar.Content.

PropDescription
onOpenAutoFocus(event: Event) => void
Event handler called when focus moves into the component after opening. It can be prevented by calling event.preventDefault.
onCloseAutoFocus(event: Event) => void
Event handler called when focus moves to the trigger after closing. It can be prevented by calling event.preventDefault.
onEscapeKeyDown(event: KeyboardEvent) => void
Event handler called when the escape key is down. It can be prevented by calling event.preventDefault.
onPointerDownOutside(event: PointerDownOutsideEvent) => void
Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling event.preventDefault.
onFocusOutside(event: FocusOutsideEvent) => void
Event handler called when the focus moves outside the bounds of the component. It can be prevented by calling event.preventDefault.
onInteractOutside(event: InteractOutsideEvent) => void
Event handler called when an interaction (pointer or focus event) happens outside the bounds of the component. It can be prevented by calling event.preventDefault.
PropDescription
sizenumber
The size of the arrow.
PropDescription
textValuestring
Optional text used for typeahead purposes. By default, the typeahead behavior will use the .textContent of the Menubar.ItemLabel part if provided, or fallback to the .textContent of the Menubar.Item. Use this when the content is complex, or you have non-textual content inside.
disabledboolean
Whether the item is disabled or not.
closeOnSelectboolean
Whether the menu should close when the item is activated.
onSelect() => void
Event handler called when the user selects an item (via mouse or keyboard).
Data attributeDescription
data-disabledPresent when the item is disabled.
data-highlightedPresent when the item is highlighted.

Menubar.ItemLabel, Menubar.ItemDescription and Menubar.ItemIndicator shares the same data-attributes.

PropDescription
forceMountboolean
Used to force mounting when more control is needed. Useful when controlling animation with SolidJS animation libraries.
PropDescription
valuestring
The controlled value of the menu radio item to check.
defaultValuestring
The value of the menu radio item that should be checked when initially rendered. Useful when you do not need to control the state of the radio group.
onChange(value: string) => void
Event handler called when the value changes.
disabledboolean
Whether the radio group is disabled or not.
PropDescription
valuestring
The value of the menu item radio.
textValuestring
Optional text used for typeahead purposes. By default, the typeahead behavior will use the .textContent of the Menubar.ItemLabel part if provided, or fallback to the .textContent of the Menubar.Item. Use this when the content is complex, or you have non-textual content inside.
disabledboolean
Whether the item is disabled or not.
closeOnSelectboolean
Whether the menu should close when the item is checked.
onSelect() => void
Event handler called when the user selects an item (via mouse or keyboard).
Data attributeDescription
data-disabledPresent when the item is disabled.
data-checkedPresent when the item is checked.
data-highlightedPresent when the item is highlighted.
PropDescription
checkedboolean
The controlled checked state of the item.
defaultCheckedboolean
The default checked state when initially rendered. Useful when you do not need to control the checked state.
onChange(checked: boolean) => void
Event handler called when the checked state of the item changes.
textValuestring
Optional text used for typeahead purposes. By default, the typeahead behavior will use the .textContent of the Menubar.ItemLabel part if provided, or fallback to the .textContent of the Menubar.Item. Use this when the content is complex, or you have non-textual content inside.
indeterminateboolean
Whether the item is in an indeterminate state.
disabledboolean
Whether the item is disabled or not.
closeOnSelectboolean
Whether the menu should close when the item is checked/unchecked.
onSelect() => void
Event handler called when the user selects an item (via mouse or keyboard).
Data attributeDescription
data-disabledPresent when the item is disabled.
data-indeterminatePresent when the item is in an indeterminate state.
data-checkedPresent when the item is checked.
data-highlightedPresent when the item is highlighted.
PropDescription
openboolean
The controlled open state of the sub menu.
defaultOpenboolean
The default open state when initially rendered. Useful when you do not need to control the open state.
onOpenChange(open: boolean) => void
Event handler called when the open state of the sub menu changes.

Menubar.Sub also accepts the following props to customize the placement of the Menubar.SubContent.

PropDescription
getAnchorRect(anchor?: HTMLElement) => AnchorRect | undefined
Function that returns the trigger element's DOMRect.
gutternumber
The distance between the sub menu content and the trigger element. By default, it's 0 plus half of the arrow offset, if it exists.
shiftnumber
The skidding of the sub menu content along the trigger element.
slideboolean
Whether the sub menu content should slide when it overflows.
overlapboolean
Whether the sub menu content can overlap the trigger element when it overflows.
fitViewportboolean
Whether the sub menu content should fit the viewport. If this is set to true, the sub menu content will have maxWidth and maxHeight set to the viewport size. This will be exposed to CSS as --kb-popper-available-width and --kb-popper-available-height.
hideWhenDetachedboolean
Whether to hide the sub menu content when the trigger element becomes occluded.
detachedPaddingnumber
The minimum padding in order to consider the trigger element occluded.
arrowPaddingnumber
The minimum padding between the arrow and the sub menu content corner.
overflowPaddingnumber
The minimum padding between the sub menu content and the viewport edge. This will be exposed to CSS as --kb-popper-overflow-padding.
PropDescription
textValuestring
Optional text used for typeahead purposes. By default, the typeahead behavior will use the .textContent of the Menubar.SubTrigger. Use this when the content is complex, or you have non-textual content inside.
disabledboolean
Whether the sub menu trigger is disabled or not.
Data attributeDescription
data-disabledPresent when the item is disabled.
data-highlightedPresent when the item is highlighted.
PropDescription
onEscapeKeyDown(event: KeyboardEvent) => void
Event handler called when the escape key is down. It can be prevented by calling event.preventDefault.
onPointerDownOutside(event: PointerDownOutsideEvent) => void
Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling event.preventDefault.
onFocusOutside(event: FocusOutsideEvent) => void
Event handler called when the focus moves outside the bounds of the component. It can be prevented by calling event.preventDefault.
onInteractOutside(event: InteractOutsideEvent) => void
Event handler called when an interaction (pointer or focus event) happens outside the bounds of the component. It can be prevented by calling event.preventDefault.

Rendered elements

ComponentDefault rendered element
Menubardiv
Menubar.Menunone
Menubar.Triggerdiv
Menubar.Icondiv
Menubar.PortalPortal
Menubar.Contentdiv
Menubar.Arrowdiv
Menubar.Separatorhr
Menubar.Groupdiv
Menubar.GroupLabelspan
Menubar.Subnone
Menubar.SubTriggerdiv
Menubar.SubContentdiv
Menubar.Itemdiv
Menubar.ItemLabeldiv
Menubar.ItemDescriptiondiv
Menubar.ItemIndicatordiv
Menubar.RadioGroupdiv
Menubar.RadioItemdiv
Menubar.CheckboxItemdiv

Accessibility

Keyboard Interactions

KeyDescription
SpaceWhen focus is on an item, activates the item.
EnterWhen focus is on an item, activates the item.
ArrowDownWhen focus is on an item, moves focus to the next item.
ArrowUpWhen focus is on an item, moves focus to the previous item.
ArrowRightWhen focus is on an item (not sub menu trigger), moves focus to the next menu.
ArrowLeftWhen focus is on an item (not sub menu item), moves focus to the previous menu.
ArrowRight / ArrowLeftWhen focus is on a sub menu trigger, opens or closes the submenu depending on reading direction.
HomeWhen focus is on an item, moves focus to first item.
EndWhen focus is on an item, moves focus to last item.
EscCloses the context menu.