| Name | Type | Default | Description |
|---|---|---|---|
items* | MenuItemProps |MenuGroupProps[] | | An array of MenuItemProps. |
accent | RegExp |(primary: string) => RegExp | | Use to accent(make bold) portions of the primary text. Useful for filter/search results. If passed a function, that function will be passed each items primary text. |
aria-describedby | string | | Additional information to announce to screen reader users. Read before menu navigation instructions. |
arrowNavigationUnsupported | boolean | | Flag to indicate that Right/Left arrow navigation for expand/collapse parent items is not available. Will accept enter if not selectable parent, otherwise falls back to shift + space. |
className | string | | Additional CSS classes. |
emptyText | string | | A simple message to display when there are no items. |
focusControlEl | HTMLElement |undefined | | Override for default active-descendant focus control element in menu |
focusElOnClose | boolean | | Override whether the menu automatically focuses the control element on close |
footer | ReactNode | | Footer region. |
header | ReactNode | | Header region. |
id | string | | HTML ID. |
loadMore | (id: ) => void | | Callback to fetch more items |
loading | boolean | false
| Show a Progress indicator at the end of a list where newly loaded items will be appended. |
mode | 'action' |'multi-select' |'single-select' | "action"
| Indicates intent for the menu. As of now item types can not be mixed. |
onItemActive | (id: ) => void | | A top level handler for all item pseudo focus events. This is convenient way to detect which item is active to react by updating state or performing an action. |
onItemClick | (id: , e: MouseEvent<AcceptedMouseEventElement>) => void | | A top level handler for all item clicks. This is convenient way to detect which item was clicked to react by updating state or performing an action. Both an item's onClick and this will be called if both are passed. |
onItemCollapse | (id: ) => void | | A top level handler for capturing when nested items have been collapsed / "back" button clicks. |
onItemExpand | (id: , e: MouseEvent<AcceptedMouseEventElement>) => void | | A top level handler for clicks on parent items to expand their child items. This is convenient way to detect when an item is expanded. For lazy loading this would be a good time to set an item's items. Both an item's onExpand and this will be called if both are passed. |
ref | Ref<HTMLDivElement> | | Ref placed on the root menu element. |
scrollAt | number | 7
| Item height will grow or shrink based on item count. Use this indicate at which item the menu should begin its scroll. |
variant | 'drill-down' |'flyout' | "drill-down"
| Always recommended to go for default drill-down variant for better accessibility. When flyout variant is selected, its recommended not to have more than 1 nested level |
Menu
The Menu component is a list of actions or choices that renders vertically and is styled to look like a classic dropdown menu. Menus within the Cosmos design system are typically opened from a MenuButton.
For more information on how to use the features and props for this component, check out the developer documentation.
Usage
Menus are primarily composed of items that are built on top of SummaryItems. This means that each item in a Menu can accept props such as primary and secondary text, as well as a visual region. The secondary prop for Menu items should be provided as an array of text. This will render a MetaList below the primary text. They may also be configured to display a count or tooltip containing more relevant information about the item. Items may be given an href and/or an onClick handler as well as an onExpand handler in the event of the item triggering a new Menu to open. Individual items may also be set as disabled.
The Menu component is capable of rendering items in a defined hierarchy. Each item can itself have a list of items, as well as a list of ancestors. This nesting capability allows for several layers of Menus to be composed within one singular Menu, with the proper navigation between the hierarchy being managed by the component.
Menus can be used in one of two variants: drill-down and flyout. The drill-down variant will utilize the same UI space for all nested Menus, replacing each Menu when a new one is opened. The flyout variant will preserve the visual state of all Menus. As items with children are opened, the new Menus will render within Popovers next to the triggering item.
The Menu component also supports different modes. The default mode is action. Each leaf item should have an associated onClick or href prop that will be triggered when a user clicks on it. The single-select mode allows a user to select one item from a Menu at a time. The multi-select mode allows a user to select multiple items. For both single-select and multi-select modes, you should indicate items that have been chosen with the selected prop on each item.
There are several other features that the Menu component supports including loading states, lazy loading, accent highlighting, and more. Check out all of he available props for this component in the props table below.