Menu

A menu offers a list of choices to the user, such as a set of actions or functions.

View sourceView on npmReport an issueWAI-ARIA

Usage

Empty state

A menu can have an empty state.

Align and direction

The align prop aligns the Menu relative to the trigger and the direction prop controls the direction the Menu will render.

Sizes

A menu can have different sizes.

Sections

A menu's items can be grouped by sections.

Dividers

A menu's items can be separated by dividers.

Item icons

A menu item can have icons.

Item end icon

A menu item can have end icons. However, think twice before adding end icons, start icons should be your go-to.

Item description

A menu item can have a description.

A description can be paired with an icon.

A description can also be paired with an avatar.

Disabled item

A menu item can be disabled.

They can also be disabled using the disabledKeys prop on the Menu component.

Validation

A menu item can be set as invalid using the isInvalid prop.

Selection

A menu supports multiple selection modes. By default, selection is disabled, however this can be changed by settings the selectionMode property to "single" or "multiple".

Section-level selection

Each section in a menu may have independent selection states. This works the same way as described above for the entire menu, but operates at the section level instead.

Custom Trigger

MenuTrigger works out of the box with any pressable component (e.g. Button, Link, etc.).

Custom trigger elements such as third party components and other DOM elements are also supported by wrapping them with the <Pressable> component.

Dynamic items

A menu items can be rendered dynamically.

Controlled

The selectedKey and open state can be handled in controlled mode.

Opening a modal

A ModalTrigger component won't work with a menu item. Still, it can be done with a custom modal trigger.

Submenu

A menu can have submenus, which are menus that open when hovering or clicking on a menu item.

Props

MenuTrigger

align?

The horizontal alignment of the popup relative to the trigger.

Defaults to 'start'.
direction?

The direction the open will open relative to the trigger.

allowFlip?

Whether or not the popup can flip when it will overflow it's boundary area.

trigger?

How the menu is triggered.

Defaults to 'press'.
isOpen?

Whether the overlay is open by default (controlled).

defaultOpen?

Whether the overlay is open by default (uncontrolled).

Menu

size?

The size of the menu.

Defaults to sm.
popoverProps?

The props for the popover.

style?

The inline style for the element. A function may be provided to compute the style based on component state.

children?

The contents of the collection.

escapeKeyBehavior?

Whether pressing the escape key should clear selection in the menu or not.

Most experiences should not modify this option as it eliminates a keyboard user's ability to easily clear selection. Only use if the escape key is being handled externally or should not trigger selection clearing contextually.

Defaults to 'clearSelection'.
autoFocus?

Where the focus should be set.

shouldFocusWrap?

Whether keyboard navigation is circular.

items?

Item objects in the collection.

disabledKeys?

The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.

selectionMode?

The type of selection that is allowed in the collection.

disallowEmptySelection?

Whether the collection allows empty selection.

selectedKeys?

The currently selected keys in the collection (controlled).

defaultSelectedKeys?

The initial selected keys in the collection (uncontrolled).

renderEmptyState?

Provides content to display when there are no items in the list.

dependencies?

Values that should invalidate the item cache when using dynamic collections.

className?

The CSS className for the element. A function may be provided to compute the class based on component state.

MenuItem

children

The contents of the item.

isInvalid?

Whether or not the item is invalid

size?

The size of the MenuItem.

Defaults to sm.
style?

The inline style for the element. A function may be provided to compute the style based on component state.

id?

The unique id of the item.

value?

The object value that this item represents. When using dynamic collections, this is set automatically.

textValue?

A string representation of the item's contents, used for features like typeahead.

isDisabled?

Whether the item is disabled.

className?

The CSS className for the element. A function may be provided to compute the class based on component state.

href?

A URL to link to. See MDN.

hrefLang?

Hints at the human language of the linked URL. SeeMDN.

target?

The target window for the link. See MDN.

rel?

The relationship between the linked resource and the current page. See MDN.

download?

Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.

ping?

A space-separated list of URLs to ping when the link is followed. See MDN.

referrerPolicy?

How much of the referrer to send when following the link. See MDN.

routerOptions?

Options for the configured client side router.

MenuSection

style?

The inline style for the element.

children?

Static child items or a function to render children.

items?

Item objects in the section.

id?

The unique id of the section.

value?

The object value that this section represents. When using dynamic collections, this is set automatically.

dependencies?

Values that should invalidate the item cache when using dynamic collections.

className?

The CSS className for the element.

selectionMode?

The type of selection that is allowed in the collection.

disallowEmptySelection?

Whether the collection allows empty selection.

selectedKeys?

The currently selected keys in the collection (controlled).

defaultSelectedKeys?

The initial selected keys in the collection (uncontrolled).

disabledKeys?

The currently disabled keys in the collection (controlled).

Divider

style?

The inline style for the element.

orientation?

The orientation of the separator.

Defaults to 'horizontal'.
elementType?

The HTML element type that will be used to render the separator.

className?

The CSS className for the element.

SubmenuTrigger

children

The contents of the SubmenuTrigger. The first child should be an Item (the trigger) and the second child should be the Popover (for the submenu).

Migration Notes

Coming from Orbiter, you should be aware of the following changes:

MenuTrigger

  • allowPreventOverflow has been removed.
  • closeOnSelect has been removed.
  • open has been renamed to isOpen.

Menu

  • autoFocusTarget has been removed.
  • disabled has been removed, set the disabled items as disabledKeys instead.
  • fluid has been removed.
  • nodes has been removed.
  • validationState has been removed. isInvalid should be used instead on the MenuItem.

MenuItem

  • disabled has been renamed to isDisabled

MenuSection

  • title has been removed from MenuSection, use Header as a children instead

Miscellaneous

  • Item has been renamed MenuItem
  • Section has been renamed MenuSection
  • We cannot add a tooltip on a MenuItem anymore