Skip to Content
Sponsor

Menu

An accessible dropdown menu for the common dropdown menu button design pattern. Menu uses roving tabIndex for focus management.

Import#

Chakra UI exports 8 components for rendering menus:

  • Menu: The wrapper component provides context, state, and focus management.
  • MenuList: The wrapper for the menu items. Must be a direct child of Menu.
  • MenuButton: The trigger for the menu list. Must be a direct child of Menu.
  • MenuItem: The trigger that handles menu selection. Must be a direct child of a MenuList.
  • MenuGroup: A wrapper to group related menu items.
  • MenuDivider: A visual separator for menu items and groups.
  • MenuOptionGroup: A wrapper for checkable menu items (radio and checkbox)
  • MenuItemOption: The checkable menu item, to be used with MenuOptionGroup

Usage#

Editable Example

Accessing the internal state#

To access the internal state of the Menu, use a function as children (commonly known as a render prop). You'll get access to the internal state isOpen and method onClose.

Editable Example

Letter Navigation#

When focus is on the MenuButton or within the MenuList and you type a letter key, a search begins. Focus will move to the first MenuItem that starts with the letter you typed.

Open the menu, try and type any letter, (say "S") to see the focus movement.

Editable Example

Just another example.#

Editable Example

Adding menu commands#

You can add custom menu icons and commands (or hotkeys) for each menu by passing the command prop.

Adding menu transition#

You can add transition support for the menu by importing the MenuTransition component.

It's important to use the sx prop for the transitions to work properly. For some reason, it doesn't work with the style native prop

Rendering menu in a portal#

To render menus in a portal, import the Portal component and wrap the MenuList within the Portal.

To group related MenuItems, use the MenuGroup component and pass it a title for the group name.

Editable Example

You can compose a menu for table headers to help with sorting and filtering options. Use the MenuOptionGroup and MenuItemOption components.

Editable Example

Accessibility#

Keyboard Interaction#

KeyAction
Enter or SpaceWhen MenuButton receives focus, opens the menu and places focus on the first menu item
ArrowDownWhen MenuButton receives focus, opens the menu and moves focus to the first menu item
ArrowUpWhen MenuButton receives focus, opens the menu and moves focus to the last menu item
EscapeWhen the menu is open, closes the menu and sets focus to the MenuButton
Tabno effect
HomeWhen the menu is open, moves focus to the first item.
EndWhen the menu is open, moves focus to the last item.
A-Z or a-zWhen the menu is open, moves focus to the next menu item with a label that starts with the typed character if such an menu item exists.

ARIA roles#

For MenuButton:

  • role is set to button.
  • aria-haspopup is set to menu.
  • When the menu is displayed, MenuButton has aria-expanded set to true.
  • MenuButton has aria-controls set to the id of the MenuList.

For MenuList:

  • The MenuItem has role menu.

Props#

NameTypeDefaultDescription
childrenReact.ReactNodeThe children of the menu must be MenuButton and MenuList
isOpenbooleanIf true, the menu will be opened
autoSelectbooleantrueThe menu will select the first enabled item when it opens
closeOnBlurbooleantrueIf true, the menu will close on outside click or blur
closeOnSelectbooleantrueIf true, the menu will close on menu item select
placementPopperJS.placementThe placement of the MenuList
NameType
childrenReact.ReactNode
onClickReact.MouseEventHandler
onKeyDownReact.KeyboardEventHandler
NameTypeDescription
childrenReact.ReactNodeThe content of the MenuList, should be the MenuItem component
onClickReact.MouseEventHandlerFunction to be called when you click on the menu item
onBlurReact.FocusEventHandlerFunction to be called when you blur out of the menu list
NameTypeDescription
isDisabledbooleanIf true, the menu item will be disabled
onClickReact.MouseEventHandlerFunction that is called on click and enter/space keypress
onKeyDownReact.KeyboardEventHanderFunction that is called on keydown
rolemenuitem, menuitemradio, menuitemcheckboxThe ARIA role of the menuitem
NameTypeDescription
childrenReact.ReactNodeThe content of the menu group
titlestringThe title of the menu group
NameTypeDescription
childrenReact.ReactNodeThe content of the option group
titlestringTitle of the option group
typeradio, checkboxUsed to add roles menuitemradio or menuitemcheckbox
defaultValuestring, number, Array<string or number>The initial value of the option group
valuestring, number, Array<string or number>The value of the option group
onChange(value) => voidFunction called when selection changes

MenuItemOption extends Box so you can pass all box props in addition to these:

NameTypeDescription
isDisabledbooleanIf true, the option item will be disabled
valueStringOrNumberThe value of the option item
typeradio, checkboxUsed to add menuitemradio or menuitemcheckbox roles to the option
Edit this page