Example
On mobile devices, the Menu automatically displays in a tray instead of a popover to improve usability.
Patterns
Collections
Menu implements react-stately collection components, <Item> and <Section>.
Static collections, seen in the example above, can be used when the full list of options is known ahead of time.
Dynamic collections, as shown below, can be used when the options come from an external data source such as an API call, or update over time. Providing the data in this way allows the menu to cache the rendering of each item, which improves performance.
Keys and IDs
Dynamic collections provide an iterable list of items to the menu. Each item accepts a unique key prop, which is passed to the handler.
If the item objects contain an id property, as shown in the example above, then this is used automatically and a key prop is not required.
Sections
Use the <Section> component to group related items. Each Section takes a title and key prop.
Sections used with dynamic items are populated from a hierarchical data structure. Similar to the menu itself, Section takes an array of data using the items prop.
Sections without a title must provide an aria-label for accessibility.
Selection
Enable the selection of items with the selectionMode prop. See the react-stately selection docs for more information about selection.
Use defaultSelectedKeys to provide a default set of selected items (uncontrolled) and selectedKeys to set the selected items (controlled). The selected keys must match the key prop of the items, which will be passed to the onSelectionChange handler when the user selects an item.
Set the selectionMode to "multiple" to allow more than one selection.
Links
By default, interacting with an item in a menu triggers onAction and optionally onSelectionChange depending on the selectionMode. Alternatively, items may be links to another page or website. This can be achieved by passing the href prop to the <Item> component. Link items in a menu are not selectable.
Slots
Icons, keyboard shortcuts and descriptions can be added as children of an item, to better communicate the effect of each option. If a description is added, the prop slot="description" must be used to distinguish it from the <Text> label.
Props
Actions
When no selection mode is set, or it is set to "none" (default), use the onAction callback to handle press events on items.
Focus
Providing an autoFocus prop to the Menu sets the focus of a menu item, once open.
When the selection mode is “single” or “multiple” the first selected item will be focused by default. You turn off this behaviour by passing autoFocus=false to the menu.
Disabled
When the trigger element is disabled the menu cannot be invoked.
You can also provide disabledKeys to limit selection.
Alignment
The align prop aligns the menu relative to the trigger, while the direction prop controls the direction the menu will render.