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.

install	`yarn add @react-aria/menu`
version	3.4.3
usage	`import {useMenu, useMenuItem, useMenuSection} from '@react-aria/menu'`

View ARIA spec

W3C

API#

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

useMenuItem<T>(
  props: AriaMenuItemProps,
  state: TreeState<T>,
  ref: RefObject<HTMLElement>
): MenuItemAria

useMenuSection(
  (props: AriaMenuSectionProps
)): MenuSectionAria

Features#

There is no native element to implement a menu in HTML that is widely supported. useMenu helps achieve accessible menu components that can be styled as needed.

Note: useMenu only handles the menu itself. For a dropdown menu, combine with useMenuTrigger.

Exposed to assistive technology as a menu with menuitem children using ARIA
Support for single, multiple, or no selection
Support for disabled items
Support for sections
Complex item labeling support for accessibility
Support for mouse, touch, and keyboard interactions
Tab stop focus management
Keyboard navigation support including arrow keys, home/end, page up/down
Automatic scrolling support during keyboard navigation
Typeahead to allow focusing items by typing text
Virtualized scrolling support for performance with long lists

Anatomy#

A menu consists of a container element, with a list of menu items or groups inside. useMenu, useMenuItem, and useMenuSection handle exposing this to assistive technology using ARIA, along with handling keyboard, mouse, and interactions to support selection and focus behavior.

useMenu returns props that you should spread onto the menu container element:

Name	Type	Description
`menuProps`	`HTMLAttributes<HTMLElement>`	Props for the menu element.

useMenuItem returns props for an individual item and its children:

Name	Type	Description
`menuItemProps`	`HTMLAttributes<HTMLElement>`	Props for the menu item element.
`labelProps`	`HTMLAttributes<HTMLElement>`	Props for the main text element inside the menu item.
`descriptionProps`	`HTMLAttributes<HTMLElement>`	Props for the description text element inside the menu item, if any.
`keyboardShortcutProps`	`HTMLAttributes<HTMLElement>`	Props for the keyboard shortcut text element inside the item, if any.

useMenuSection returns props for a section:

Name	Type	Description
`itemProps`	`HTMLAttributes<HTMLElement>`	Props for the wrapper list item.
`headingProps`	`HTMLAttributes<HTMLElement>`	Props for the heading element, if any.
`groupProps`	`HTMLAttributes<HTMLElement>`	Props for the group element.

State is managed by the useTreeState hook from @react-stately/tree. The state object should be passed as an option to each of the above hooks.

If a menu, menu item, or group does not have a visible label, an aria-label or aria-labelledby prop must be passed instead to identify the element to assistive technology.

State management#

useMenu requires knowledge of the items in the menu in order to handle keyboard navigation and other interactions. It does this using the Collection interface, which is a generic interface to access sequential unique keyed data. You can implement this interface yourself, e.g. by using a prop to pass a list of item objects, but useTreeState from @react-stately/tree implements a JSX based interface for building collections instead. See Collection Components for more information, and Collection Interface for internal details.

In addition, useTreeState manages the state necessary for multiple selection and exposes a SelectionManager, which makes use of the collection to provide an interface to update the selection state. For more information, see Selection.

Example#

This example uses HTML <ul> and <li> elements to represent the menu with the first item disabled, and applies props from useMenu and useMenuItem.

import {useMenu, useMenuItem} from '@react-aria/menu';
import {useTreeState} from '@react-stately/tree';
import {Item} from '@react-stately/collections';
import {useFocus} from '@react-aria/interactions';
import {mergeProps} from '@react-aria/utils';

function Menu(props) {
  // Create state based on the incoming props
  let state = useTreeState({...props, selectionMode: 'none'});

  // Get props for the menu element
  let ref = React.useRef();
  let {menuProps} = useMenu(props, state, ref);

  return (
    <ul
      {...menuProps}
      ref={ref}
      style={{
        padding: 0,
        listStyle: 'none',
        border: '1px solid gray',
        maxWidth: 250
      }}>
      {[...state.collection].map(item => (
        <MenuItem
          key={item.key}
          item={item}
          state={state}
          onAction={props.onAction} />
      ))}
    </ul>
  );
}

function MenuItem({item, state, onAction}) {
  // Get props for the menu item element
  let ref = React.useRef();
  let isDisabled = state.disabledKeys.has(item.key);
  let isFocused = state.selectionManager.focusedKey === item.key;

  let {menuItemProps} = useMenuItem({
    key: item.key,
    isDisabled,
    onAction
  }, state, ref);

  return (
    <li
      {...menuItemProps}
      ref={ref}
      style={{
        background: isFocused ? 'gray' : 'transparent',
        color: isFocused ? 'white' : null,
        padding: '2px 5px',
        outline: 'none',
        cursor: isDisabled ? 'default' : 'pointer'
      }}>
      {item.rendered}
    </li>
  );
}

<Menu onAction={alert} aria-label="Actions" disabledKeys={['one']}>
  <Item key="one">One</Item>
  <Item key="two">Two</Item>
  <Item key="three">Three</Item>
</Menu>

import {useMenu, useMenuItem} from '@react-aria/menu';
import {useTreeState} from '@react-stately/tree';
import {Item} from '@react-stately/collections';
import {useFocus} from '@react-aria/interactions';
import {mergeProps} from '@react-aria/utils';

function Menu(props) {
  // Create state based on the incoming props
  let state = useTreeState({
    ...props,
    selectionMode: 'none'
  });

  // Get props for the menu element
  let ref = React.useRef();
  let { menuProps } = useMenu(props, state, ref);

  return (
    <ul
      {...menuProps}
      ref={ref}
      style={{
        padding: 0,
        listStyle: 'none',
        border: '1px solid gray',
        maxWidth: 250
      }}
    >
      {[...state.collection].map((item) => (
        <MenuItem
          key={item.key}
          item={item}
          state={state}
          onAction={props.onAction}
        />
      ))}
    </ul>
  );
}

function MenuItem({ item, state, onAction }) {
  // Get props for the menu item element
  let ref = React.useRef();
  let isDisabled = state.disabledKeys.has(item.key);
  let isFocused =
    state.selectionManager.focusedKey === item.key;

  let { menuItemProps } = useMenuItem(
    {
      key: item.key,
      isDisabled,
      onAction
    },
    state,
    ref
  );

  return (
    <li
      {...menuItemProps}
      ref={ref}
      style={{
        background: isFocused ? 'gray' : 'transparent',
        color: isFocused ? 'white' : null,
        padding: '2px 5px',
        outline: 'none',
        cursor: isDisabled ? 'default' : 'pointer'
      }}
    >
      {item.rendered}
    </li>
  );
}

<Menu
  onAction={alert}
  aria-label="Actions"
  disabledKeys={['one']}
>
  <Item key="one">One</Item>
  <Item key="two">Two</Item>
  <Item key="three">Three</Item>
</Menu>

import {
  useMenu,
  useMenuItem
} from '@react-aria/menu';
import {useTreeState} from '@react-stately/tree';
import {Item} from '@react-stately/collections';
import {useFocus} from '@react-aria/interactions';
import {mergeProps} from '@react-aria/utils';

function Menu(props) {
  // Create state based on the incoming props
  let state =
    useTreeState({
      ...props,
      selectionMode:
        'none'
    });

  // Get props for the menu element
  let ref = React
    .useRef();
  let { menuProps } =
    useMenu(
      props,
      state,
      ref
    );

  return (
    <ul
      {...menuProps}
      ref={ref}
      style={{
        padding: 0,
        listStyle:
          'none',
        border:
          '1px solid gray',
        maxWidth: 250
      }}
    >
      {[
        ...state
          .collection
      ].map((item) => (
        <MenuItem
          key={item.key}
          item={item}
          state={state}
          onAction={props
            .onAction}
        />
      ))}
    </ul>
  );
}

function MenuItem(
  {
    item,
    state,
    onAction
  }
) {
  // Get props for the menu item element
  let ref = React
    .useRef();
  let isDisabled = state
    .disabledKeys.has(
      item.key
    );
  let isFocused =
    state
      .selectionManager
      .focusedKey ===
      item.key;

  let { menuItemProps } =
    useMenuItem(
      {
        key: item.key,
        isDisabled,
        onAction
      },
      state,
      ref
    );

  return (
    <li
      {...menuItemProps}
      ref={ref}
      style={{
        background:
          isFocused
            ? 'gray'
            : 'transparent',
        color: isFocused
          ? 'white'
          : null,
        padding:
          '2px 5px',
        outline: 'none',
        cursor:
          isDisabled
            ? 'default'
            : 'pointer'
      }}
    >
      {item.rendered}
    </li>
  );
}

<Menu
  onAction={alert}
  aria-label="Actions"
  disabledKeys={[
    'one'
  ]}
>
  <Item key="one">
    One
  </Item>
  <Item key="two">
    Two
  </Item>
  <Item key="three">
    Three
  </Item>
</Menu>

Sections#

This example shows how a menu can support sections with separators and headings using props from useMenuSection. This is accomplished using four extra elements: an <li> between the sections to represent the separator, an <li> to contain the heading <span> element, and a <ul> to contain the child items. This structure is necessary to ensure HTML semantics are correct.

import {Section} from '@react-stately/collections';
import {useMenuSection} from '@react-aria/menu';
import {useSeparator} from '@react-aria/separator';

function Menu(props) {
  let state = useTreeState({...props, selectionMode: 'none'});
  let ref = React.useRef();
  let {menuProps} = useMenu(props, state, ref);

  return (
    <ul
      {...menuProps}
      ref={ref}
      style={{
        margin: 0,
        padding: 0,
        listStyle: 'none',
        border: '1px solid gray',
        maxWidth: 250
      }}>
      {[...state.collection].map(item => (
        <MenuSection
          key={item.key}
          section={item}
          state={state}
          onAction={props.onAction} />
      ))}
    </ul>
  );
}

function MenuSection({section, state, onAction}) {
  let {itemProps, headingProps, groupProps} = useMenuSection({
    heading: section.rendered,
    'aria-label': section['aria-label']
  });

  let {separatorProps} = useSeparator({
    elementType: 'li'
  });

  // If the section is not the first, add a separator element.
  // The heading is rendered inside an <li> element, which contains
  // a <ul> with the child items.
  return <>
    {section.key !== state.collection.getFirstKey() &&
      <li
        {...separatorProps}
        style={{
          borderTop: '1px solid gray',
          margin: '2px 5px'
        }} />
    }
    <li {...itemProps}>
      {section.rendered &&
        <span
          {...headingProps}
          style={{
            fontWeight: 'bold',
            fontSize: '1.1em',
            padding: '2px 5px',
          }}>
          {section.rendered}
        </span>
      }
      <ul
        {...groupProps}
        style={{
          padding: 0,
          listStyle: 'none'
        }}>
        {[...section.childNodes].map(node =>
          <MenuItem
            key={node.key}
            item={node}
            state={state}
            onAction={onAction} />
        )}
      </ul>
    </li>
  </>;
}

function MenuItem({item, state, onAction}) {
  // Same as in the first example...
}

<Menu onAction={alert} aria-label="Actions">
  <Section title="Section 1">
    <Item key="section1-item1">One</Item>
    <Item key="section1-item2">Two</Item>
    <Item key="section1-item3">Three</Item>
  </Section>
  <Section title="Section 2">
    <Item key="section2-item1">One</Item>
    <Item key="section2-item2">Two</Item>
    <Item key="section2-item3">Three</Item>
  </Section>
</Menu>

import {Section} from '@react-stately/collections';
import {useMenuSection} from '@react-aria/menu';
import {useSeparator} from '@react-aria/separator';

function Menu(props) {
  let state = useTreeState({
    ...props,
    selectionMode: 'none'
  });
  let ref = React.useRef();
  let { menuProps } = useMenu(props, state, ref);

  return (
    <ul
      {...menuProps}
      ref={ref}
      style={{
        margin: 0,
        padding: 0,
        listStyle: 'none',
        border: '1px solid gray',
        maxWidth: 250
      }}
    >
      {[...state.collection].map((item) => (
        <MenuSection
          key={item.key}
          section={item}
          state={state}
          onAction={props.onAction}
        />
      ))}
    </ul>
  );
}

function MenuSection({ section, state, onAction }) {
  let { itemProps, headingProps, groupProps } =
    useMenuSection({
      heading: section.rendered,
      'aria-label': section['aria-label']
    });

  let { separatorProps } = useSeparator({
    elementType: 'li'
  });

  // If the section is not the first, add a separator element.
  // The heading is rendered inside an <li> element, which contains
  // a <ul> with the child items.
  return (
    <>
      {section.key !== state.collection.getFirstKey() &&
        (
          <li
            {...separatorProps}
            style={{
              borderTop: '1px solid gray',
              margin: '2px 5px'
            }}
          />
        )}
      <li {...itemProps}>
        {section.rendered &&
          (
            <span
              {...headingProps}
              style={{
                fontWeight: 'bold',
                fontSize: '1.1em',
                padding: '2px 5px'
              }}
            >
              {section.rendered}
            </span>
          )}
        <ul
          {...groupProps}
          style={{
            padding: 0,
            listStyle: 'none'
          }}
        >
          {[...section.childNodes].map((node) => (
            <MenuItem
              key={node.key}
              item={node}
              state={state}
              onAction={onAction}
            />
          ))}
        </ul>
      </li>
    </>
  );
}

function MenuItem({ item, state, onAction }) {
  // Same as in the first example...
}

<Menu onAction={alert} aria-label="Actions">
  <Section title="Section 1">
    <Item key="section1-item1">One</Item>
    <Item key="section1-item2">Two</Item>
    <Item key="section1-item3">Three</Item>
  </Section>
  <Section title="Section 2">
    <Item key="section2-item1">One</Item>
    <Item key="section2-item2">Two</Item>
    <Item key="section2-item3">Three</Item>
  </Section>
</Menu>

import {Section} from '@react-stately/collections';
import {useMenuSection} from '@react-aria/menu';
import {useSeparator} from '@react-aria/separator';

function Menu(props) {
  let state =
    useTreeState({
      ...props,
      selectionMode:
        'none'
    });
  let ref = React
    .useRef();
  let { menuProps } =
    useMenu(
      props,
      state,
      ref
    );

  return (
    <ul
      {...menuProps}
      ref={ref}
      style={{
        margin: 0,
        padding: 0,
        listStyle:
          'none',
        border:
          '1px solid gray',
        maxWidth: 250
      }}
    >
      {[
        ...state
          .collection
      ].map((item) => (
        <MenuSection
          key={item.key}
          section={item}
          state={state}
          onAction={props
            .onAction}
        />
      ))}
    </ul>
  );
}

function MenuSection(
  {
    section,
    state,
    onAction
  }
) {
  let {
    itemProps,
    headingProps,
    groupProps
  } = useMenuSection({
    heading:
      section.rendered,
    'aria-label':
      section[
        'aria-label'
      ]
  });

  let {
    separatorProps
  } = useSeparator({
    elementType: 'li'
  });

  // If the section is not the first, add a separator element.
  // The heading is rendered inside an <li> element, which contains
  // a <ul> with the child items.
  return (
    <>
      {section.key !==
          state
            .collection
            .getFirstKey() &&
        (
          <li
            {...separatorProps}
            style={{
              borderTop:
                '1px solid gray',
              margin:
                '2px 5px'
            }}
          />
        )}
      <li {...itemProps}>
        {section
          .rendered &&
          (
            <span
              {...headingProps}
              style={{
                fontWeight:
                  'bold',
                fontSize:
                  '1.1em',
                padding:
                  '2px 5px'
              }}
            >
              {section
                .rendered}
            </span>
          )}
        <ul
          {...groupProps}
          style={{
            padding: 0,
            listStyle:
              'none'
          }}
        >
          {[
            ...section
              .childNodes
          ].map(
            (node) => (
              <MenuItem
                key={node
                  .key}
                item={node}
                state={state}
                onAction={onAction}
              />
            )
          )}
        </ul>
      </li>
    </>
  );
}

function MenuItem(
  {
    item,
    state,
    onAction
  }
) {
  // Same as in the first example...
}

<Menu
  onAction={alert}
  aria-label="Actions"
>
  <Section title="Section 1">
    <Item key="section1-item1">
      One
    </Item>
    <Item key="section1-item2">
      Two
    </Item>
    <Item key="section1-item3">
      Three
    </Item>
  </Section>
  <Section title="Section 2">
    <Item key="section2-item1">
      One
    </Item>
    <Item key="section2-item2">
      Two
    </Item>
    <Item key="section2-item3">
      Three
    </Item>
  </Section>
</Menu>

By default, menu items that only contain text will be labeled by the contents of the item. For items that have more complex content (e.g. icons, multiple lines of text, keyboard shortcuts, etc.), use labelProps, descriptionProps, and keyboardShortcutProps from useMenuItem as needed to apply to the main text element of the menu item, its description, and keyboard shortcut text. This improves screen reader announcement.

NOTE: menu items cannot contain interactive content (e.g. buttons, checkboxes, etc.).

This example shows how labelProps, descriptionProps, and keyboardShortcutProps can be applied to child elements of the item to apply ARIA properties returned by useMenuItem. This is done using React.cloneElement in this example, but you can use context or other approaches for this as well.

function Menu(props) {
  // Same as the first example...
}

function MenuItem({item, state, onAction}) {
  // Get props for the menu item element and child elements
  let ref = React.useRef();
  let isDisabled = state.disabledKeys.has(item.key);

  let {
    menuItemProps,
    labelProps,
    descriptionProps,
    keyboardShortcutProps
  } = useMenuItem({
    key: item.key,
    isDisabled,
    onAction
  }, state, ref);

  // Handle focus events so we can apply highlighted
  // style to the focused menu item
  let [isFocused, setFocused] = React.useState(false);
  let {focusProps} = useFocus({onFocusChange: setFocused});

  // Pull out the three expected children. We will clone them
  // and add the necessary props for accessibility.
  let [title, description, shortcut] = item.rendered;

  return (
    <li
      {...mergeProps(menuItemProps, focusProps)}
      ref={ref}
      style={{
        background: isFocused ? 'gray' : 'transparent',
        color: isFocused ? 'white' : null,
        padding: '2px 5px',
        outline: 'none',
        cursor: 'pointer',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'space-between'
      }}>
      <div>
        {React.cloneElement(title, labelProps)}
        {React.cloneElement(description, descriptionProps)}
      </div>
      {React.cloneElement(shortcut, keyboardShortcutProps)}
    </li>
  );
}

<Menu onAction={alert} aria-label="Actions">
  <Item textValue="Copy" key="copy">
    <div><strong>Copy</strong></div>
    <div>Copy the selected text</div>
    <kbd>⌘C</kbd>
  </Item>
  <Item textValue="Cut" key="cut">
    <div><strong>Cut</strong></div>
    <div>Cut the selected text</div>
    <kbd>⌘X</kbd>
  </Item>
  <Item textValue="Paste" key="paste">
    <div><strong>Paste</strong></div>
    <div>Paste the copied text</div>
    <kbd>⌘V</kbd>
  </Item>
</Menu>

function Menu(props) {
  // Same as the first example...
}

function MenuItem({ item, state, onAction }) {
  // Get props for the menu item element and child elements
  let ref = React.useRef();
  let isDisabled = state.disabledKeys.has(item.key);

  let {
    menuItemProps,
    labelProps,
    descriptionProps,
    keyboardShortcutProps
  } = useMenuItem(
    {
      key: item.key,
      isDisabled,
      onAction
    },
    state,
    ref
  );

  // Handle focus events so we can apply highlighted
  // style to the focused menu item
  let [isFocused, setFocused] = React.useState(false);
  let { focusProps } = useFocus({
    onFocusChange: setFocused
  });

  // Pull out the three expected children. We will clone them
  // and add the necessary props for accessibility.
  let [title, description, shortcut] = item.rendered;

  return (
    <li
      {...mergeProps(menuItemProps, focusProps)}
      ref={ref}
      style={{
        background: isFocused ? 'gray' : 'transparent',
        color: isFocused ? 'white' : null,
        padding: '2px 5px',
        outline: 'none',
        cursor: 'pointer',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'space-between'
      }}
    >
      <div>
        {React.cloneElement(title, labelProps)}
        {React.cloneElement(description, descriptionProps)}
      </div>
      {React.cloneElement(shortcut, keyboardShortcutProps)}
    </li>
  );
}

<Menu onAction={alert} aria-label="Actions">
  <Item textValue="Copy" key="copy">
    <div>
      <strong>Copy</strong>
    </div>
    <div>Copy the selected text</div>
    <kbd>⌘C</kbd>
  </Item>
  <Item textValue="Cut" key="cut">
    <div>
      <strong>Cut</strong>
    </div>
    <div>Cut the selected text</div>
    <kbd>⌘X</kbd>
  </Item>
  <Item textValue="Paste" key="paste">
    <div>
      <strong>Paste</strong>
    </div>
    <div>Paste the copied text</div>
    <kbd>⌘V</kbd>
  </Item>
</Menu>

function Menu(props) {
  // Same as the first example...
}

function MenuItem(
  {
    item,
    state,
    onAction
  }
) {
  // Get props for the menu item element and child elements
  let ref = React
    .useRef();
  let isDisabled = state
    .disabledKeys.has(
      item.key
    );

  let {
    menuItemProps,
    labelProps,
    descriptionProps,
    keyboardShortcutProps
  } = useMenuItem(
    {
      key: item.key,
      isDisabled,
      onAction
    },
    state,
    ref
  );

  // Handle focus events so we can apply highlighted
  // style to the focused menu item
  let [
    isFocused,
    setFocused
  ] = React.useState(
    false
  );
  let { focusProps } =
    useFocus({
      onFocusChange:
        setFocused
    });

  // Pull out the three expected children. We will clone them
  // and add the necessary props for accessibility.
  let [
    title,
    description,
    shortcut
  ] = item.rendered;

  return (
    <li
      {...mergeProps(
        menuItemProps,
        focusProps
      )}
      ref={ref}
      style={{
        background:
          isFocused
            ? 'gray'
            : 'transparent',
        color: isFocused
          ? 'white'
          : null,
        padding:
          '2px 5px',
        outline: 'none',
        cursor:
          'pointer',
        display: 'flex',
        alignItems:
          'center',
        justifyContent:
          'space-between'
      }}
    >
      <div>
        {React
          .cloneElement(
            title,
            labelProps
          )}
        {React
          .cloneElement(
            description,
            descriptionProps
          )}
      </div>
      {React
        .cloneElement(
          shortcut,
          keyboardShortcutProps
        )}
    </li>
  );
}

<Menu
  onAction={alert}
  aria-label="Actions"
>
  <Item
    textValue="Copy"
    key="copy"
  >
    <div>
      <strong>
        Copy
      </strong>
    </div>
    <div>
      Copy the selected
      text
    </div>
    <kbd>⌘C</kbd>
  </Item>
  <Item
    textValue="Cut"
    key="cut"
  >
    <div>
      <strong>
        Cut
      </strong>
    </div>
    <div>
      Cut the selected
      text
    </div>
    <kbd>⌘X</kbd>
  </Item>
  <Item
    textValue="Paste"
    key="paste"
  >
    <div>
      <strong>
        Paste
      </strong>
    </div>
    <div>
      Paste the copied
      text
    </div>
    <kbd>⌘V</kbd>
  </Item>
</Menu>

Internationalization#

useMenu handles some aspects of internationalization automatically. For example, type to select is implemented with an Intl.Collator for internationalized string matching. You are responsible for localizing all menu item labels for content that is passed into the menu.

RTL#

In right-to-left languages, the menu items should be mirrored. The text content should be aligned to the right, and keyboard shortcuts should be aligned left. Ensure that your CSS accounts for this.

Name	Type	Description
`children`	`CollectionChildren<T>`	The contents of the collection.
`isVirtualized`	`boolean`	Whether the menu uses virtual scrolling.
`keyboardDelegate`	`KeyboardDelegate`	An optional keyboard delegate implementation for type to select, to override the default.
`autoFocus`	`boolean \| FocusStrategy`	Where the focus should be set.
`shouldFocusWrap`	`boolean`	Whether keyboard navigation is circular.
`onAction`	`( (key: Key )) => void`	Handler that is called when an item is selected.
`items`	`Iterable<T>`	Item objects in the collection.
`disabledKeys`	`Iterable<Key>`	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`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 )) => any`	Handler that is called when the selection changes.
`id`	`string`	The element's unique identifier. See MDN.
`aria-label`	`string`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	Identifies the element (or elements) that provide a detailed, extended description for the object.

Method	Description
`getKeyBelow( (key: Key )): Key`	Returns the key visually below the given one, or `null` for none.
`getKeyAbove( (key: Key )): Key`	Returns the key visually above the given one, or `null` for none.
`getKeyLeftOf( (key: Key )): Key`	Returns the key visually to the left of the given one, or `null` for none.
`getKeyRightOf( (key: Key )): Key`	Returns the key visually to the right of the given one, or `null` for none.
`getKeyPageBelow( (key: Key )): Key`	Returns the key visually one page below the given one, or `null` for none.
`getKeyPageAbove( (key: Key )): Key`	Returns the key visually one page above the given one, or `null` for none.
`getFirstKey( (key?: Key, , global?: boolean )): Key`	Returns the first key, or `null` for none.
`getLastKey( (key?: Key, , global?: boolean )): Key`	Returns the last key, or `null` for none.
`getKeyForSearch( (search: string, , fromKey?: Key )): Key`	Returns the next key after `fromKey` that matches the given search string, or `null` for none.

'first' | 'last'

CollectionElement<T>
  | CollectionElement<T>[]
  | (
    (item: T
  )) => CollectionElement<T>

SectionElement<T> | ItemElement<T>

ReactElement<SectionProps<T>>

Name	Type	Description
`children`	`ItemElement<T> \| ItemElement<T>[] \| ItemRenderer<T>`	Static child items or a function to render children.
`title`	`ReactNode`	Rendered contents of the section, e.g. a header.
`aria-label`	`string`	An accessibility label for the section.
`items`	`Iterable<T>`	Item objects in the section.

ReactElement<ItemProps<T>>

Name	Type	Description
`children`	`ReactNode`	Rendered contents of the item or child items.
`title`	`ReactNode`	Rendered contents of the item if `children` contains child items.
`textValue`	`string`	A string representation of the item's contents, used for features like typeahead.
`aria-label`	`string`	An accessibility label for this item.
`childItems`	`Iterable<T>`	A list of child item objects. Used for dynamic collections.
`hasChildItems`	`boolean`	Whether this item has children, even if not loaded yet.

(
  (item: T
)) => ItemElement<T>

'none'
  | 'single'
  | 'multiple'

'all' | Set<Key>

Properties

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

Methods

Method	Description
`toggleKey( (key: Key )): void`	Toggles the expanded state for an item by its key.

A generic interface to access a readonly sequential collection of unique keyed items.

Properties

Name	Type	Description
`size`	`number`	The number of items in the collection.

Methods

Method	Description
`getKeys(): Iterable<Key>`	Iterate over all keys in the collection.
`getItem( (key: Key )): T`	Get an item by its key.
`at( (idx: number )): T`	Get an item by the index of its key.
`getKeyBefore( (key: Key )): Key \| null`	Get the key that comes before the given key in the collection.
`getKeyAfter( (key: Key )): Key \| null`	Get the key that comes after the given key in the collection.
`getFirstKey(): Key \| null`	Get the first key in the collection.
`getLastKey(): Key \| null`	Get the last key in the collection.

Name	Type	Description
`type`	`string`	The type of item this node represents.
`key`	`Key`	A unique key for the node.
`value`	`T`	The object value the node was created from.
`level`	`number`	The level of depth this node is at in the heirarchy.
`hasChildNodes`	`boolean`	Whether this item has children, even if not loaded yet.
`childNodes`	`Iterable<Node<T>>`	The loaded children of this node.
`rendered`	`ReactNode`	The rendered contents of this node (e.g. JSX).
`textValue`	`string`	A string value for this node, used for features like typeahead.
`aria-label`	`string`	An accessibility label for this node.
`index`	`number`	The index of this node within its parent.
`wrapper`	`( (element: ReactElement )) => ReactElement`	A function that should be called to wrap the rendered node.
`parentKey`	`Key`	The key of the parent node.
`prevKey`	`Key`	The key of the node before this node.
`nextKey`	`Key`	The key of the node after this node.
`props`	`any`	Additional properties specific to a particular node type.

An interface for reading and updating multiple selection state.

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	Whether the first or last child of the focused key should receive focus.
`selectedKeys`	`Set<Key>`	The currently selected keys in the collection.
`rawSelection`	`Selection`	The raw selection value for the collection. Either 'all' for select all, or a set of keys.
`isEmpty`	`boolean`	Whether the selection is empty.
`isSelectAll`	`boolean`	Whether all items in the collection are selected.
`firstSelectedKey`	`Key \| null`
`lastSelectedKey`	`Key \| null`

Methods

Method	Description
`constructor( collection: Collection<Node<unknown>>, state: MultipleSelectionState, options?: SelectionManagerOptions ): void`
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key, , childFocusStrategy?: FocusStrategy )): void`	Sets the focused key.
`isSelected( (key: Key )): void`	Returns whether a key is selected.
`extendSelection( (toKey: Key )): void`	Extends the selection to the given key.
`toggleSelection( (key: Key )): void`	Toggles whether the given key is selected.
`replaceSelection( (key: Key )): void`	Replaces the selection with only the given key.
`setSelectedKeys( (keys: Iterable<Key> )): void`	Replaces the selection with the given keys.
`selectAll(): void`	Selects all items in the collection.
`clearSelection(): void`	Removes all keys from the selection.
`toggleSelectAll(): void`	Toggles between select all and an empty selection.
`select( (key: Key, , e?: PressEvent \| LongPressEvent \| PointerEvent )): void`
`isSelectionEqual( (selection: Set<Key> )): void`	Returns whether the current selection is equal to the given selection.
`canSelectItem( (key: Key )): void`

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectedKeys`	`Selection`	The currently selected keys in the collection.
`disabledKeys`	`Set<Key>`	The currently disabled keys in the collection.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	Whether the first or last child of the focused key should receive focus.

Methods

Method	Description
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`setSelectedKeys( (keys: Selection )): void`	Sets the selected keys in the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key, , child?: FocusStrategy )): void`	Sets the focused key, and optionally, whether the first or last child of that key should receive focus.

'toggle' | 'replace'

Name	Type	Description
`allowsCellSelection`	`boolean`

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`	The type of press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`HTMLElement`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'

Name	Type	Description
`type`	`'longpressstart' \| 'longpressend' \| 'longpress'`	The type of long press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`HTMLElement`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.

Name	Type	Description
`menuProps`	`HTMLAttributes<HTMLElement>`	Props for the menu element.

Name	Type	Default	Description
`isDisabled`	`boolean`	—	Whether the menu item is disabled.
`isSelected`	`boolean`	—	Whether the menu item is selected.
`aria-label`	`string`	—	A screen reader only label for the menu item.
`key`	`Key`	—	The unique key for the menu item.
`onClose`	`() => void`	—	Handler that is called when the menu should close after selecting an item.
`closeOnSelect`	`boolean`	`true`	Whether the menu should close when the menu item is selected.
`isVirtualized`	`boolean`	—	Whether the menu item is contained in a virtual scrolling menu.
`onAction`	`( (key: Key )) => void`	—	Handler that is called when the user activates the item.

Name	Type	Description
`menuItemProps`	`HTMLAttributes<HTMLElement>`	Props for the menu item element.
`labelProps`	`HTMLAttributes<HTMLElement>`	Props for the main text element inside the menu item.
`descriptionProps`	`HTMLAttributes<HTMLElement>`	Props for the description text element inside the menu item, if any.
`keyboardShortcutProps`	`HTMLAttributes<HTMLElement>`	Props for the keyboard shortcut text element inside the item, if any.

Name	Type	Description
`heading`	`ReactNode`	The heading for the section.
`aria-label`	`string`	An accessibility label for the section. Required if `heading` is not present.

Name	Type	Description
`itemProps`	`HTMLAttributes<HTMLElement>`	Props for the wrapper list item.
`headingProps`	`HTMLAttributes<HTMLElement>`	Props for the heading element, if any.
`groupProps`	`HTMLAttributes<HTMLElement>`	Props for the group element.

Provides state management for tree-like components. Handles building a collection of items from props, item expanded state, and manages multiple selection state.

useTreeState<T>(
  (props: TreeProps<T>
)): TreeState<T>

Name	Type	Description
`children`	`CollectionChildren<T>`	The contents of the collection.
`items`	`Iterable<T>`	Item objects in the collection.
`disabledKeys`	`Iterable<Key>`	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`expandedKeys`	`Iterable<Key>`	The currently expanded keys in the collection (controlled).
`defaultExpandedKeys`	`Iterable<Key>`	The initial expanded keys in the collection (uncontrolled).
`onExpandedChange`	`( (keys: Set<Key> )) => any`	Handler that is called when items are expanded or collapsed.
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`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 )) => any`	Handler that is called when the selection changes.

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

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

Provides the behavior and accessibility implementation for an item in a menu. See useMenu for more details about menus.

useMenuItem<T>(
  props: AriaMenuItemProps,
  state: TreeState<T>,
  ref: RefObject<HTMLElement>
): MenuItemAria

Provides the behavior and accessibility implementation for a section in a menu. See useMenu for more details about menus.

useMenuSection(
  (props: AriaMenuSectionProps
)): MenuSectionAria

useMenu

API#

Features#

Anatomy#

State management#

Example#

Sections#

Complex menu items#

Internationalization#

RTL#

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods