--- id: menu category: overlay title: Menu package: '@chakra-ui/menu' description: An accessible dropdown menu for the common dropdown menu button design pattern. Menu uses roving tabIndex for focus management. video: 'https://youtu.be/Q-AMFseuFrk' --- ## 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`. ```js import { Menu, MenuButton, MenuList, MenuItem, MenuItemOption, MenuGroup, MenuOptionGroup, MenuDivider, } from '@chakra-ui/react' ``` ## Usage ```jsx }> Actions Download Create a Copy Mark as Draft Delete Attend a Workshop ``` ### 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`. ```jsx {({ isOpen }) => ( <> }> {isOpen ? 'Close' : 'Open'} Download alert('Kagebunshin')}>Create a Copy )} ``` ### Customizing the button The default `MenuButton` can be styled using the usual styled-system props, but it starts off plainly styled. Using the `as` prop of the `MenuButton`, you can render a custom component instead of the default `MenuButton`. For instance, you can use Chakra's `Button` component, or your own custom component. > If you decide to pass your own component to `MenuButton`, it needs to accept a > `ref` so that the `MenuList` can be positioned correctly. You can use Chakra's > `forwardRef` to supply the `ref` along with being able to use Chakra props. > Without a `ref`, the `MenuList` will render in an undefined position. See the documentation on setting up the [forwardRef](/docs/components/recipes/as-prop#option-1-using-forwardref-from-chakra-uireact) with your custom component. ### 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. ```jsx File New File New Window Open... Save File ``` ### Just another example ```jsx }> Your Cats

Fluffybuns the Destroyer

Simon the pensive ``` ### Adding icons and commands You can add icon to each `MenuItem` by passing the `icon` prop. To add a commands (or hotkeys) to menu items, you can use the `command` prop. ```jsx } variant='outline' /> } command='⌘T'> New Tab } command='⌘N'> New Window } command='⌘⇧N'> Open Closed Tab } command='⌘O'> Open File... ``` ### Lazily mounting MenuItem By default, the `Menu` component renders all children of `MenuList` to the DOM, meaning that invisible menu items are still rendered but are hidden by styles. If you want to defer rendering of each children of `MenuList` until that menu is open, you can use the `isLazy` prop. This is useful if your `Menu` needs to be extra performant, or make network calls on mount that should only happen when the component is displayed. ```jsx Open menu {/* MenuItems are not rendered unless Menu is open */} New Window Open Closed Tab Open File ``` ### Rendering menu in a portal To render menus in a portal, import the `Portal` component and wrap the `MenuList` within the `Portal`. ```jsx Open menu Menu 1 New Window Open Closed Tab Open File ``` ### MenuGroup To group related `MenuItem`s, use the `MenuGroup` component and pass it a `title` for the group name. ```jsx Profile My Account Payments Docs FAQ ``` ### MenuItem as a link To render a `MenuItem` as a link, use the attributes `as` and `href`. ```jsx Open menu Link 1 Link 2 ``` ## Menu option groups You can compose a menu for table headers to help with sorting and filtering options. Use the `MenuOptionGroup` and `MenuItemOption` components. ```jsx MenuItem Ascending Descending Email Phone Country ``` ## Accessibility ### Keyboard Interaction | Key | Action | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `Enter` or `Space` | When `MenuButton` receives focus, opens the menu and places focus on the first menu item. | | `ArrowDown` | When `MenuButton` receives focus, opens the menu and moves focus to the first menu item. | | `ArrowUp` | When `MenuButton` receives focus, opens the menu and moves focus to the last menu item. | | `Escape` | When the menu is open, closes the menu and sets focus to the `MenuButton`. | | `Tab` | no effect | | `Home` | When the menu is open, moves focus to the first item. | | `End` | When the menu is open, moves focus to the last item. | | `A-Z` or `a-z` | When 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, `aria-expanded` is set to `true`. - `aria-controls` is set to the `id` of the `MenuList`. **For `MenuList`:** - `role` is set to `menu`. - `aria-orientation` is set to `vertical`. **For `MenuItem`:** - `role` is set to `menuitem`. - Gets one of these roles `menuitem`/`menuitemradio`/ `menuitemcheckbox`.