useMenu

Provides the behavior and accessibility implementation for a menu component. A menu displays a list of actions or options that a user can choose.

Example

Button.css

Popover.css

Example

Button.css

Popover.css

import {MenuButton, MenuItem} from './Menu';

<MenuButton aria-label="Actions" onAction={key => alert(key)}>
  <MenuItem id="copy">Copy</MenuItem>
  <MenuItem id="cut">Cut</MenuItem>
  <MenuItem id="paste">Paste</MenuItem>
</MenuButton>

API

<MenuTrigger>
  <Button />
  <Popover>
    <Menu>
      <MenuItem>
        <Text slot="label" />
        <Text slot="description" />
        <Keyboard />
        <SelectionIndicator />
      </MenuItem>
      <Separator />
      <MenuSection>
        <Header />
        <MenuItem />
      </MenuSection>
      <SubmenuTrigger>
        <MenuItem />
        <Popover>
          <Menu />
        </Popover>
      </SubmenuTrigger>
    </Menu>
  </Popover>
</MenuTrigger>

useMenuTriggerState(props: MenuTriggerProps): RootMenuTriggerStateuseTreeState<T>(props: TreeProps<T>): TreeState<T>

useMenuTrigger<T>(
  props: AriaMenuTriggerProps,
state: MenuTriggerState,
ref: RefObject<Element | null>
): MenuTriggerAria<T>

useMenu<T>(
  props: AriaMenuOptions<T>,
state: TreeState<T>,
ref: RefObject<HTMLElement | null>
): MenuAria

useMenuItem<T>(
  props: AriaMenuItemProps,
state: TreeState<T>,
ref: RefObject<FocusableElement | null>
): MenuItemAria

useMenuSection(props: AriaMenuSectionProps): MenuSectionAria

MenuTriggerState

Properties

Name	Type
`focusStrategy`	`FocusStrategy \| null`
Controls which item will be auto focused when the menu opens.
`point`	`Point \| null`
The cursor position when the overlay was triggered, relative to the window viewport.

Methods

`open(focusStrategy?: FocusStrategy \| null): void`
Opens the menu.
`toggle(focusStrategy?: FocusStrategy \| null): void`
Toggles the menu.
`setOpen(isOpen: boolean): void`
Sets whether the overlay is open.
`close(): void`
Closes the overlay.
`setPoint(point: Point): void`
Sets the cursor position relative to the window viewport.

TreeState

Properties

Name	Type
`collection`	`Collection<Node<T>>`
A collection of items in the tree.
`expandedKeys`	`Set<Key>`
A set of keys for items that are expanded.
`selectionManager`	`SelectionManager`
A selection manager to read and update multiple selection state.

`disabledKeys`	`Set<Key>`
A set of keys for items that are disabled.

Methods

`toggleKey(key: Key): void`
Toggles the expanded state for an item by its key.
`setExpandedKeys(keys: Set<Key>): void`
Replaces the set of expanded keys.

AriaMenuTriggerProps

Name	Type
`type`	`'menu' \| 'listbox'`
The type of menu that the menu trigger opens.
`isDisabled`	`boolean`
Whether menu trigger is disabled.
`trigger`	`MenuTriggerType`
How menu is triggered.

MenuTriggerAria

Name	Type
`menuTriggerProps`	`AriaButtonProps`
Props for the menu trigger element.
`menuProps`	`AriaMenuOptions<T>`
Props for the menu.

AriaMenuOptions

Name	Type
`isVirtualized`	`boolean`
Whether the menu uses virtual scrolling.
`keyboardDelegate`	`KeyboardDelegate`
An optional keyboard delegate implementation for type to select, to override the default.
`shouldUseVirtualFocus`	`boolean`
Whether the menu items should use virtual focus instead of being focused directly.

`items`	`Iterable<T>`
Item objects in the collection.

`selectionMode`	`SelectionMode`
The type of selection that is allowed in the collection.
`selectedKeys`	`'all' \| Iterable<Key>`
The currently selected keys in the collection (controlled).
`defaultSelectedKeys`	`'all' \| Iterable<Key>`
The initial selected keys in the collection (uncontrolled).
`onSelectionChange`	`(keys: Selection) => void`
Handler that is called when the selection changes.
`disabledKeys`	`Iterable<Key>`
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`disallowEmptySelection`	`boolean`
Whether the collection allows empty selection.
`shouldFocusWrap`	`boolean`
Whether keyboard navigation is circular.
`escapeKeyBehavior`	`'clearSelection' \| 'none'`
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.

MenuAria

Name	Type
`menuProps`	`DOMAttributes`
Props for the menu element.

AriaMenuItemProps

Name	Type
`key`	`Key`
The unique key for the menu item.
`isVirtualized`	`boolean`
Whether the menu item is contained in a virtual scrolling menu.
`selectionManager`	`SelectionManager`
Override of the selection manager. By default, `state.selectionManager` is used.

MenuItemAria

Name	Type
`menuItemProps`	`DOMAttributes`
Props for the menu item element.
`labelProps`	`DOMAttributes`
Props for the main text element inside the menu item.
`descriptionProps`	`DOMAttributes`
Props for the description text element inside the menu item, if any.
`keyboardShortcutProps`	`DOMAttributes`
Props for the keyboard shortcut text element inside the item, if any.
`isFocused`	`boolean`
Whether the item is currently focused.
`isFocusVisible`	`boolean`
Whether the item is keyboard focused.
`isSelected`	`boolean`
Whether the item is currently selected.
`isPressed`	`boolean`
Whether the item is currently in a pressed state.
`isDisabled`	`boolean`
Whether the item is disabled.

AriaMenuSectionProps

Name	Type
`heading`	`ReactNode`
The heading for the section.

MenuSectionAria

Name	Type
`itemProps`	`DOMAttributes`
Props for the wrapper list item.
`headingProps`	`DOMAttributes`
Props for the heading element, if any.
`groupProps`	`DOMAttributes`
Props for the group element.