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`
version	3.35.0
usage	`import {useMenuTrigger, useMenu, useMenuItem, useMenuSection} from 'react-aria'`

View ARIA pattern

W3C

API#

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

Features#

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

Exposed to assistive technology as a button with a menu using ARIA
Support for single, multiple, or no selection
Support for disabled items
Support for sections
Complex item labeling support for accessibility
Keyboard navigation support including arrow keys, home/end, page up/down
Automatic scrolling support during keyboard navigation
Keyboard support for opening the menu using the arrow keys, including automatically focusing the first or last item accordingly
Typeahead to allow focusing items by typing text
Support for use with virtualized lists

Anatomy#

A menu trigger consists of a button or other trigger element combined with a popup menu, with a list of menu items or groups inside. useMenuTrigger, 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.

useMenuTrigger returns props that you should spread onto the appropriate element:

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

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

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

useMenuItem returns props for an individual item and its children:

Name	Type	Description
`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.
`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.

useMenuSection returns props for a section:

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

State for the trigger is managed by the useMenuTriggerState hook from @react-stately/menu. State for the menu itself is managed by the useTreeState hook from @react-stately/tree. These state objects should be passed to the appropriate React Aria 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.

Example#

A menu consists of several components: a menu button to toggle the menu popup, and the menu itself, which contains items or sections of items. We'll go through each component one by one.

MenuButton#

We'll start with the MenuButton component, which is what will trigger our menu to appear. This uses the useMenuTrigger and useMenuTriggerState hooks. The Popover and Button components used in this example are independent, and can be shared by many other components. The code is available below, and documentation is available on the corresponding pages.

import type {MenuTriggerProps} from 'react-stately';
import {useMenuTrigger} from 'react-aria';
import {Item, useMenuTriggerState} from 'react-stately';

// Reuse the Popover, and Button from your component library. See below for details.
import {Button, Popover} from 'your-component-library';

interface MenuButtonProps<T> extends AriaMenuProps<T>, MenuTriggerProps {
  label?: string;
}

function MenuButton<T extends object>(props: MenuButtonProps<T>) {
  // Create state based on the incoming props
  let state = useMenuTriggerState(props);

  // Get props for the button and menu elements
  let ref = React.useRef(null);
  let { menuTriggerProps, menuProps } = useMenuTrigger<T>({}, state, ref);

  return (
    <>
      <Button
        {...menuTriggerProps}
        buttonRef={ref}
        style={{ height: 30, fontSize: 14 }}
      >
        {props.label}
        <span aria-hidden="true" style={{ paddingLeft: 5 }}>▼</span>
      </Button>
      {state.isOpen &&
        (
          <Popover state={state} triggerRef={ref} placement="bottom start">
            <Menu
              {...props}
              {...menuProps}
            />
          </Popover>
        )}
    </>
  );
}

import type {MenuTriggerProps} from 'react-stately';
import {useMenuTrigger} from 'react-aria';
import {Item, useMenuTriggerState} from 'react-stately';

// Reuse the Popover, and Button from your component library. See below for details.
import {Button, Popover} from 'your-component-library';

interface MenuButtonProps<T>
  extends AriaMenuProps<T>, MenuTriggerProps {
  label?: string;
}

function MenuButton<T extends object>(
  props: MenuButtonProps<T>
) {
  // Create state based on the incoming props
  let state = useMenuTriggerState(props);

  // Get props for the button and menu elements
  let ref = React.useRef(null);
  let { menuTriggerProps, menuProps } = useMenuTrigger<T>(
    {},
    state,
    ref
  );

  return (
    <>
      <Button
        {...menuTriggerProps}
        buttonRef={ref}
        style={{ height: 30, fontSize: 14 }}
      >
        {props.label}
        <span aria-hidden="true" style={{ paddingLeft: 5 }}>
          ▼
        </span>
      </Button>
      {state.isOpen &&
        (
          <Popover
            state={state}
            triggerRef={ref}
            placement="bottom start"
          >
            <Menu
              {...props}
              {...menuProps}
            />
          </Popover>
        )}
    </>
  );
}

import type {MenuTriggerProps} from 'react-stately';
import {useMenuTrigger} from 'react-aria';
import {
  Item,
  useMenuTriggerState
} from 'react-stately';

// Reuse the Popover, and Button from your component library. See below for details.
import {
  Button,
  Popover
} from 'your-component-library';

interface MenuButtonProps<
  T
> extends
  AriaMenuProps<T>,
  MenuTriggerProps {
  label?: string;
}

function MenuButton<
  T extends object
>(
  props: MenuButtonProps<
    T
  >
) {
  // Create state based on the incoming props
  let state =
    useMenuTriggerState(
      props
    );

  // Get props for the button and menu elements
  let ref = React.useRef(
    null
  );
  let {
    menuTriggerProps,
    menuProps
  } = useMenuTrigger<T>(
    {},
    state,
    ref
  );

  return (
    <>
      <Button
        {...menuTriggerProps}
        buttonRef={ref}
        style={{
          height: 30,
          fontSize: 14
        }}
      >
        {props.label}
        <span
          aria-hidden="true"
          style={{
            paddingLeft:
              5
          }}
        >
          ▼
        </span>
      </Button>
      {state.isOpen &&
        (
          <Popover
            state={state}
            triggerRef={ref}
            placement="bottom start"
          >
            <Menu
              {...props}
              {...menuProps}
            />
          </Popover>
        )}
    </>
  );
}

Next, let's implement the Menu component. This will appear inside the Popover when the user presses the button. It is built using the useMenu and useTreeState hooks. For each item in the collection in state, we render either a MenuItem or MenuSection (defined below) according to the item's type property.

import type {AriaMenuProps} from 'react-aria';
import {useTreeState} from 'react-stately';
import {useMenu} from 'react-aria';

function Menu<T extends object>(props: AriaMenuProps<T>) {
  // Create menu state based on the incoming props
  let state = useTreeState(props);

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

  return (
    <ul {...menuProps} ref={ref}>
      {[...state.collection].map((item) => (
        item.type === 'section'
          ? <MenuSection key={item.key} section={item} state={state} />
          : <MenuItem key={item.key} item={item} state={state} />
      ))}
    </ul>
  );
}

import type {AriaMenuProps} from 'react-aria';
import {useTreeState} from 'react-stately';
import {useMenu} from 'react-aria';

function Menu<T extends object>(props: AriaMenuProps<T>) {
  // Create menu state based on the incoming props
  let state = useTreeState(props);

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

  return (
    <ul {...menuProps} ref={ref}>
      {[...state.collection].map((item) => (
        item.type === 'section'
          ? (
            <MenuSection
              key={item.key}
              section={item}
              state={state}
            />
          )
          : (
            <MenuItem
              key={item.key}
              item={item}
              state={state}
            />
          )
      ))}
    </ul>
  );
}

import type {AriaMenuProps} from 'react-aria';
import {useTreeState} from 'react-stately';
import {useMenu} from 'react-aria';

function Menu<
  T extends object
>(
  props: AriaMenuProps<T>
) {
  // Create menu state based on the incoming props
  let state =
    useTreeState(props);

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

  return (
    <ul
      {...menuProps}
      ref={ref}
    >
      {[
        ...state
          .collection
      ].map((item) => (
        item.type ===
            'section'
          ? (
            <MenuSection
              key={item
                .key}
              section={item}
              state={state}
            />
          )
          : (
            <MenuItem
              key={item
                .key}
              item={item}
              state={state}
            />
          )
      ))}
    </ul>
  );
}

MenuItem#

Now let's implement MenuItem. This is built using useMenuItem, and the state object passed via props from Menu.

import {useMenuItem} from 'react-aria';

function MenuItem({ item, state }) {
  // Get props for the menu item element
  let ref = React.useRef(null);
  let { menuItemProps, isSelected } = useMenuItem(
    { key: item.key },
    state,
    ref
  );

  return (
    <li {...menuItemProps} ref={ref}>
      {item.rendered}
      {isSelected && <span aria-hidden="true">✅</span>}
    </li>
  );
}

import {useMenuItem} from 'react-aria';

function MenuItem({ item, state }) {
  // Get props for the menu item element
  let ref = React.useRef(null);
  let { menuItemProps, isSelected } = useMenuItem(
    { key: item.key },
    state,
    ref
  );

  return (
    <li {...menuItemProps} ref={ref}>
      {item.rendered}
      {isSelected && <span aria-hidden="true">✅</span>}
    </li>
  );
}

import {useMenuItem} from 'react-aria';

function MenuItem(
  { item, state }
) {
  // Get props for the menu item element
  let ref = React.useRef(
    null
  );
  let {
    menuItemProps,
    isSelected
  } = useMenuItem(
    { key: item.key },
    state,
    ref
  );

  return (
    <li
      {...menuItemProps}
      ref={ref}
    >
      {item.rendered}
      {isSelected && (
        <span aria-hidden="true">
          ✅
        </span>
      )}
    </li>
  );
}

Now we can render a simple menu with actionable items:

<MenuButton label="Actions" onAction={alert}>
  <Item key="copy">Copy</Item>
  <Item key="cut">Cut</Item>
  <Item key="paste">Paste</Item>
</MenuButton>

<MenuButton label="Actions" onAction={alert}>
  <Item key="copy">Copy</Item>
  <Item key="cut">Cut</Item>
  <Item key="paste">Paste</Item>
</MenuButton>

<MenuButton
  label="Actions"
  onAction={alert}
>
  <Item key="copy">
    Copy
  </Item>
  <Item key="cut">
    Cut
  </Item>
  <Item key="paste">
    Paste
  </Item>
</MenuButton>

Show CSS

[role=menu] {
  margin: 0;
  padding: 0;
  list-style: none;
  width: 200px;
}

[role=menuitem],
[role=menuitemradio],
[role=menuitemcheckbox] {
  padding: 2px 5px;
  outline: none;
  cursor: default;
  display: flex;
  justify-content: space-between;
  color: black;

  &:focus {
    background: gray;
    color: white;
  }

  &[aria-disabled] {
    color: gray;
  }
}

[role=menu] {
  margin: 0;
  padding: 0;
  list-style: none;
  width: 200px;
}

[role=menuitem],
[role=menuitemradio],
[role=menuitemcheckbox] {
  padding: 2px 5px;
  outline: none;
  cursor: default;
  display: flex;
  justify-content: space-between;
  color: black;

  &:focus {
    background: gray;
    color: white;
  }

  &[aria-disabled] {
    color: gray;
  }
}

[role=menu] {
  margin: 0;
  padding: 0;
  list-style: none;
  width: 200px;
}

[role=menuitem],
[role=menuitemradio],
[role=menuitemcheckbox] {
  padding: 2px 5px;
  outline: none;
  cursor: default;
  display: flex;
  justify-content: space-between;
  color: black;

  &:focus {
    background: gray;
    color: white;
  }

  &[aria-disabled] {
    color: gray;
  }
}

The Popover component is used to contain the menu. It can be shared between many other components, including ComboBox, Select, and others. See usePopover for more examples of popovers.

Show code

import {DismissButton, Overlay, usePopover} from 'react-aria';
import type {AriaPopoverProps} from 'react-aria';
import type {OverlayTriggerState} from 'react-stately';

interface PopoverProps extends Omit<AriaPopoverProps, 'popoverRef'> {
  children: React.ReactNode;
  state: OverlayTriggerState;
}

function Popover({ children, state, ...props }: PopoverProps) {
  let popoverRef = React.useRef(null);
  let { popoverProps, underlayProps } = usePopover({
    ...props,
    popoverRef
  }, state);

  return (
    <Overlay>
      <div {...underlayProps} style={{ position: 'fixed', inset: 0 }} />
      <div
        {...popoverProps}
        ref={popoverRef}
        style={{
          ...popoverProps.style,
          background: 'lightgray',
          border: '1px solid gray'
        }}
      >
        <DismissButton onDismiss={state.close} />
        {children}
        <DismissButton onDismiss={state.close} />
      </div>
    </Overlay>
  );
}

import {
  DismissButton,
  Overlay,
  usePopover
} from 'react-aria';
import type {AriaPopoverProps} from 'react-aria';
import type {OverlayTriggerState} from 'react-stately';

interface PopoverProps
  extends Omit<AriaPopoverProps, 'popoverRef'> {
  children: React.ReactNode;
  state: OverlayTriggerState;
}

function Popover(
  { children, state, ...props }: PopoverProps
) {
  let popoverRef = React.useRef(null);
  let { popoverProps, underlayProps } = usePopover({
    ...props,
    popoverRef
  }, state);

  return (
    <Overlay>
      <div
        {...underlayProps}
        style={{ position: 'fixed', inset: 0 }}
      />
      <div
        {...popoverProps}
        ref={popoverRef}
        style={{
          ...popoverProps.style,
          background: 'lightgray',
          border: '1px solid gray'
        }}
      >
        <DismissButton onDismiss={state.close} />
        {children}
        <DismissButton onDismiss={state.close} />
      </div>
    </Overlay>
  );
}

import {
  DismissButton,
  Overlay,
  usePopover
} from 'react-aria';
import type {AriaPopoverProps} from 'react-aria';
import type {OverlayTriggerState} from 'react-stately';

interface PopoverProps
  extends
    Omit<
      AriaPopoverProps,
      'popoverRef'
    > {
  children:
    React.ReactNode;
  state:
    OverlayTriggerState;
}

function Popover(
  {
    children,
    state,
    ...props
  }: PopoverProps
) {
  let popoverRef = React
    .useRef(null);
  let {
    popoverProps,
    underlayProps
  } = usePopover({
    ...props,
    popoverRef
  }, state);

  return (
    <Overlay>
      <div
        {...underlayProps}
        style={{
          position:
            'fixed',
          inset: 0
        }}
      />
      <div
        {...popoverProps}
        ref={popoverRef}
        style={{
          ...popoverProps
            .style,
          background:
            'lightgray',
          border:
            '1px solid gray'
        }}
      >
        <DismissButton
          onDismiss={state
            .close}
        />
        {children}
        <DismissButton
          onDismiss={state
            .close}
        />
      </div>
    </Overlay>
  );
}

Button#

The Button component is used in the above example to toggle the menu. It is built using the useButton hook, and can be shared with many other components.

Show code

import {useButton} from 'react-aria';

function Button(props) {
  let ref = props.buttonRef;
  let { buttonProps } = useButton(props, ref);
  return (
    <button {...buttonProps} ref={ref} style={props.style}>
      {props.children}
    </button>
  );
}

import {useButton} from 'react-aria';

function Button(props) {
  let ref = props.buttonRef;
  let { buttonProps } = useButton(props, ref);
  return (
    <button {...buttonProps} ref={ref} style={props.style}>
      {props.children}
    </button>
  );
}

import {useButton} from 'react-aria';

function Button(props) {
  let ref =
    props.buttonRef;
  let { buttonProps } =
    useButton(
      props,
      ref
    );
  return (
    <button
      {...buttonProps}
      ref={ref}
      style={props.style}
    >
      {props.children}
    </button>
  );
}

Styled examples#

Tailwind CSS

An example of styling a Menu with Tailwind.

Dynamic collections#

Menu follows the Collection Components API, accepting both static and dynamic collections. The examples above show static collections, which 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.

As seen below, an iterable list of options is passed to the ComboBox using the items prop. Each item accepts a key prop, which is passed to the onSelectionChange handler to identify the selected item. Alternatively, if the item objects contain an id property, as shown in the example below, then this is used automatically and a key prop is not required.

function Example() {
  let items = [
    {id: 1, name: 'New'},
    {id: 2, name: 'Open'},
    {id: 3, name: 'Close'},
    {id: 4, name: 'Save'},
    {id: 5, name: 'Duplicate'},
    {id: 6, name: 'Rename'},
    {id: 7, name: 'Move'}
  ];

  return (
    <MenuButton label="Actions" items={items} onAction={alert}>
      {(item) => <Item>{item.name}</Item>}
    </MenuButton>
  );
}

function Example() {
  let items = [
    { id: 1, name: 'New' },
    { id: 2, name: 'Open' },
    { id: 3, name: 'Close' },
    { id: 4, name: 'Save' },
    { id: 5, name: 'Duplicate' },
    { id: 6, name: 'Rename' },
    { id: 7, name: 'Move' }
  ];

  return (
    <MenuButton
      label="Actions"
      items={items}
      onAction={alert}
    >
      {(item) => <Item>{item.name}</Item>}
    </MenuButton>
  );
}

function Example() {
  let items = [
    {
      id: 1,
      name: 'New'
    },
    {
      id: 2,
      name: 'Open'
    },
    {
      id: 3,
      name: 'Close'
    },
    {
      id: 4,
      name: 'Save'
    },
    {
      id: 5,
      name: 'Duplicate'
    },
    {
      id: 6,
      name: 'Rename'
    },
    {
      id: 7,
      name: 'Move'
    }
  ];

  return (
    <MenuButton
      label="Actions"
      items={items}
      onAction={alert}
    >
      {(item) => (
        <Item>
          {item.name}
        </Item>
      )}
    </MenuButton>
  );
}

Selection#

Menu supports multiple selection modes. By default, selection is disabled, however this can be changed using the selectionMode prop. Use defaultSelectedKeys to provide a default set of selected items (uncontrolled) and selectedKeys to set the selected items (controlled). The value of the selected keys must match the key prop of the items. See the react-stately Selection docs for more details.

import type {Selection} from 'react-stately';

function Example() {
  let [selected, setSelected] = React.useState<Selection>(
    new Set(['sidebar', 'console'])
  );

  return (
    <>
      <MenuButton
        label="View"
        selectionMode="multiple"
        selectedKeys={selected}
        onSelectionChange={setSelected}
      >
        <Item key="sidebar">Sidebar</Item>
        <Item key="searchbar">Searchbar</Item>
        <Item key="tools">Tools</Item>
        <Item key="console">Console</Item>
      </MenuButton>
      <p>
        Current selection (controlled):{' '}
        {selected === 'all' ? 'all' : [...selected].join(', ')}
      </p>
    </>
  );
}

import type {Selection} from 'react-stately';

function Example() {
  let [selected, setSelected] = React.useState<Selection>(
    new Set(['sidebar', 'console'])
  );

  return (
    <>
      <MenuButton
        label="View"
        selectionMode="multiple"
        selectedKeys={selected}
        onSelectionChange={setSelected}
      >
        <Item key="sidebar">Sidebar</Item>
        <Item key="searchbar">Searchbar</Item>
        <Item key="tools">Tools</Item>
        <Item key="console">Console</Item>
      </MenuButton>
      <p>
        Current selection (controlled): {selected === 'all'
          ? 'all'
          : [...selected].join(', ')}
      </p>
    </>
  );
}

import type {Selection} from 'react-stately';

function Example() {
  let [
    selected,
    setSelected
  ] = React.useState<
    Selection
  >(
    new Set([
      'sidebar',
      'console'
    ])
  );

  return (
    <>
      <MenuButton
        label="View"
        selectionMode="multiple"
        selectedKeys={selected}
        onSelectionChange={setSelected}
      >
        <Item key="sidebar">
          Sidebar
        </Item>
        <Item key="searchbar">
          Searchbar
        </Item>
        <Item key="tools">
          Tools
        </Item>
        <Item key="console">
          Console
        </Item>
      </MenuButton>
      <p>
        Current selection
        (controlled):
        {' '}
        {selected ===
            'all'
          ? 'all'
          : [...selected]
            .join(', ')}
      </p>
    </>
  );
}

Sections#

Menu supports sections with separators and headings in order to group options. Sections can be used by wrapping groups of Items in a Section component. Each Section takes a title and key prop. To implement sections, implement the ListBoxSection component referenced above using the useMenuSection hook. It will include 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 {useMenuSection, useSeparator} from 'react-aria';

function MenuSection({ section, state }) {
  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}
            />
          ))}
        </ul>
      </li>
    </>
  );
}

import {useMenuSection, useSeparator} from 'react-aria';

function MenuSection({ section, state }) {
  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}
            />
          ))}
        </ul>
      </li>
    </>
  );
}

import {
  useMenuSection,
  useSeparator
} from 'react-aria';

function MenuSection(
  { section, state }
) {
  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}
              />
            )
          )}
        </ul>
      </li>
    </>
  );
}

Static items#

With this in place, we can now render a static menu with multiple sections:

import {Section} from 'react-stately';

<MenuButton label="Actions" onAction={alert}>
  <Section title="Styles">
    <Item key="bold">Bold</Item>
    <Item key="underline">Underline</Item>
  </Section>
  <Section title="Align">
    <Item key="left">Left</Item>
    <Item key="middle">Middle</Item>
    <Item key="right">Right</Item>
  </Section>
</MenuButton>

import {Section} from 'react-stately';

<MenuButton label="Actions" onAction={alert}>
  <Section title="Styles">
    <Item key="bold">Bold</Item>
    <Item key="underline">Underline</Item>
  </Section>
  <Section title="Align">
    <Item key="left">Left</Item>
    <Item key="middle">Middle</Item>
    <Item key="right">Right</Item>
  </Section>
</MenuButton>

import {Section} from 'react-stately';

<MenuButton
  label="Actions"
  onAction={alert}
>
  <Section title="Styles">
    <Item key="bold">
      Bold
    </Item>
    <Item key="underline">
      Underline
    </Item>
  </Section>
  <Section title="Align">
    <Item key="left">
      Left
    </Item>
    <Item key="middle">
      Middle
    </Item>
    <Item key="right">
      Right
    </Item>
  </Section>
</MenuButton>

Dynamic items#

The above example shows sections with static items. Sections can also be populated from a hierarchical data structure. Similarly to the props on Menu, <Section> takes an array of data using the items prop.

import type {Selection} from 'react-stately';

function Example() {
  let [selected, setSelected] = React.useState<Selection>(new Set([1,3]));
  let openWindows = [
    {
      name: 'Left Panel',
      id: 'left',
      children: [
        {id: 1, name: 'Final Copy (1)'}
      ]
    },
    {
      name: 'Right Panel',
      id: 'right',
      children: [
        {id: 2, name: 'index.ts'},
        {id: 3, name: 'package.json'},
        {id: 4, name: 'license.txt'}
      ]
    }
  ];

  return (
    <MenuButton
      label="Window"
      items={openWindows}
      selectionMode="multiple"
      selectedKeys={selected}
      onSelectionChange={setSelected}>
      {item => (
        <Section items={item.children} title={item.name}>
          {item => <Item>{item.name}</Item>}
        </Section>
      )}
    </MenuButton>
  );
}

import type {Selection} from 'react-stately';

function Example() {
  let [selected, setSelected] = React.useState<Selection>(
    new Set([1, 3])
  );
  let openWindows = [
    {
      name: 'Left Panel',
      id: 'left',
      children: [
        { id: 1, name: 'Final Copy (1)' }
      ]
    },
    {
      name: 'Right Panel',
      id: 'right',
      children: [
        { id: 2, name: 'index.ts' },
        { id: 3, name: 'package.json' },
        { id: 4, name: 'license.txt' }
      ]
    }
  ];

  return (
    <MenuButton
      label="Window"
      items={openWindows}
      selectionMode="multiple"
      selectedKeys={selected}
      onSelectionChange={setSelected}
    >
      {(item) => (
        <Section items={item.children} title={item.name}>
          {(item) => <Item>{item.name}</Item>}
        </Section>
      )}
    </MenuButton>
  );
}

import type {Selection} from 'react-stately';

function Example() {
  let [
    selected,
    setSelected
  ] = React.useState<
    Selection
  >(new Set([1, 3]));
  let openWindows = [
    {
      name: 'Left Panel',
      id: 'left',
      children: [
        {
          id: 1,
          name:
            'Final Copy (1)'
        }
      ]
    },
    {
      name:
        'Right Panel',
      id: 'right',
      children: [
        {
          id: 2,
          name:
            'index.ts'
        },
        {
          id: 3,
          name:
            'package.json'
        },
        {
          id: 4,
          name:
            'license.txt'
        }
      ]
    }
  ];

  return (
    <MenuButton
      label="Window"
      items={openWindows}
      selectionMode="multiple"
      selectedKeys={selected}
      onSelectionChange={setSelected}
    >
      {(item) => (
        <Section
          items={item
            .children}
          title={item
            .name}
        >
          {(item) => (
            <Item>
              {item.name}
            </Item>
          )}
        </Section>
      )}
    </MenuButton>
  );
}

Accessibility#

Sections without a title must provide an aria-label for accessibility.

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.).

To implement this, we'll update the MenuItem component to apply the ARIA properties returned by useMenuItem to the appropriate elements. In this example, we'll pull them out of props.children and use React.cloneElement to apply the props, but you may want to use a more robust approach (e.g. context).

function MenuItem({item, state}) {
  // Get props for the menu item element and child elements
  let ref = React.useRef(null);
  let {
    menuItemProps,
    labelProps,
    descriptionProps,
    keyboardShortcutProps
  } = useMenuItem({key: item.key}, state, ref);

  // 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 {...menuItemProps} ref={ref}>
      <div>
        {React.cloneElement(title, labelProps)}
        {React.cloneElement(description, descriptionProps)}
      </div>
      {React.cloneElement(shortcut, keyboardShortcutProps)}
    </li>
  );
}

<MenuButton label="Actions" onAction={alert}>
  <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>
</MenuButton>

function MenuItem({ item, state }) {
  // Get props for the menu item element and child elements
  let ref = React.useRef(null);
  let {
    menuItemProps,
    labelProps,
    descriptionProps,
    keyboardShortcutProps
  } = useMenuItem({ key: item.key }, state, ref);

  // 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 {...menuItemProps} ref={ref}>
      <div>
        {React.cloneElement(title, labelProps)}
        {React.cloneElement(description, descriptionProps)}
      </div>
      {React.cloneElement(shortcut, keyboardShortcutProps)}
    </li>
  );
}

<MenuButton label="Actions" onAction={alert}>
  <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>
</MenuButton>

function MenuItem(
  { item, state }
) {
  // Get props for the menu item element and child elements
  let ref = React.useRef(
    null
  );
  let {
    menuItemProps,
    labelProps,
    descriptionProps,
    keyboardShortcutProps
  } = useMenuItem(
    { key: item.key },
    state,
    ref
  );

  // 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
      {...menuItemProps}
      ref={ref}
    >
      <div>
        {React
          .cloneElement(
            title,
            labelProps
          )}
        {React
          .cloneElement(
            description,
            descriptionProps
          )}
      </div>
      {React
        .cloneElement(
          shortcut,
          keyboardShortcutProps
        )}
    </li>
  );
}

<MenuButton
  label="Actions"
  onAction={alert}
>
  <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>
</MenuButton>

Disabled items#

useMenu supports marking items as disabled using the disabledKeys prop. Each key in this list corresponds with the key prop passed to the Item component, or automatically derived from the values passed to the items prop. See Collections for more details.

Disabled items are not focusable or keyboard navigable, and do not trigger onAction or onSelectionChange. The isDisabled property returned by useMenuItem can be used to style the item appropriately.

<MenuButton label="Actions" onAction={alert} disabledKeys={['paste']}>
  <Item key="copy">Copy</Item>
  <Item key="cut">Cut</Item>
  <Item key="paste">Paste</Item>
</MenuButton>

<MenuButton
  label="Actions"
  onAction={alert}
  disabledKeys={['paste']}
>
  <Item key="copy">Copy</Item>
  <Item key="cut">Cut</Item>
  <Item key="paste">Paste</Item>
</MenuButton>

<MenuButton
  label="Actions"
  onAction={alert}
  disabledKeys={[
    'paste'
  ]}
>
  <Item key="copy">
    Copy
  </Item>
  <Item key="cut">
    Cut
  </Item>
  <Item key="paste">
    Paste
  </Item>
</MenuButton>

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.

This example shows how to update the MenuItem component with support for rendering an <a> element if an href prop is passed to the item. Note that you'll also need to render the Menu as a <div> instead of a <ul>, since an <a> inside a <ul> is not valid HTML.

function MenuItem({item, state}) {
  // Get props for the menu item element and child elements
  let ref = React.useRef(null);
  let {menuItemProps} = useMenuItem({key: item.key}, state, ref);
  let ElementType: React.ElementType = item.props.href ? 'a' : 'div';
  return (
    <ElementType {...menuItemProps} ref={ref}>
      {item.rendered}
    </ElementType>
  );
}

<MenuButton label="Links">
  <Item href="https://adobe.com/" target="_blank">Adobe</Item>
  <Item href="https://apple.com/" target="_blank">Apple</Item>
  <Item href="https://google.com/" target="_blank">Google</Item>
  <Item href="https://microsoft.com/" target="_blank">Microsoft</Item>
</MenuButton>

function MenuItem({ item, state }) {
  // Get props for the menu item element and child elements
  let ref = React.useRef(null);
  let { menuItemProps } = useMenuItem(
    { key: item.key },
    state,
    ref
  );
  let ElementType: React.ElementType = item.props.href
    ? 'a'
    : 'div';
  return (
    <ElementType {...menuItemProps} ref={ref}>
      {item.rendered}
    </ElementType>
  );
}

<MenuButton label="Links">
  <Item href="https://adobe.com/" target="_blank">
    Adobe
  </Item>
  <Item href="https://apple.com/" target="_blank">
    Apple
  </Item>
  <Item href="https://google.com/" target="_blank">
    Google
  </Item>
  <Item href="https://microsoft.com/" target="_blank">
    Microsoft
  </Item>
</MenuButton>

function MenuItem(
  { item, state }
) {
  // Get props for the menu item element and child elements
  let ref = React.useRef(
    null
  );
  let { menuItemProps } =
    useMenuItem(
      { key: item.key },
      state,
      ref
    );
  let ElementType:
    React.ElementType =
      item.props.href
        ? 'a'
        : 'div';
  return (
    <ElementType
      {...menuItemProps}
      ref={ref}
    >
      {item.rendered}
    </ElementType>
  );
}

<MenuButton label="Links">
  <Item
    href="https://adobe.com/"
    target="_blank"
  >
    Adobe
  </Item>
  <Item
    href="https://apple.com/"
    target="_blank"
  >
    Apple
  </Item>
  <Item
    href="https://google.com/"
    target="_blank"
  >
    Google
  </Item>
  <Item
    href="https://microsoft.com/"
    target="_blank"
  >
    Microsoft
  </Item>
</MenuButton>

Client side routing#

The <Item> component works with frameworks and client side routers like Next.js and React Router. As with other React Aria components that support links, this works via the RouterProvider component at the root of your app. See the client side routing guide to learn how to set this up.

Controlled open state#

The open state of the menu can be controlled via the defaultOpen and isOpen props

function Example() {
  let [open, setOpen] = React.useState(false);

  return (
    <>
      <p>Menu is {open ? 'open' : 'closed'}</p>
      <MenuButton
        label="View"
        isOpen={open}
        onOpenChange={setOpen}>
        <Item key="side">Side bar</Item>
        <Item key="options">Page options</Item>
        <Item key="edit">Edit Panel</Item>
      </MenuButton>
    </>
  );
}

function Example() {
  let [open, setOpen] = React.useState(false);

  return (
    <>
      <p>Menu is {open ? 'open' : 'closed'}</p>
      <MenuButton
        label="View"
        isOpen={open}
        onOpenChange={setOpen}>
        <Item key="side">Side bar</Item>
        <Item key="options">Page options</Item>
        <Item key="edit">Edit Panel</Item>
      </MenuButton>
    </>
  );
}

function Example() {
  let [open, setOpen] =
    React.useState(
      false
    );

  return (
    <>
      <p>
        Menu is {open
          ? 'open'
          : 'closed'}
      </p>
      <MenuButton
        label="View"
        isOpen={open}
        onOpenChange={setOpen}
      >
        <Item key="side">
          Side bar
        </Item>
        <Item key="options">
          Page options
        </Item>
        <Item key="edit">
          Edit Panel
        </Item>
      </MenuButton>
    </>
  );
}

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 button should be mirrored. The arrow should be on the left, and the label should be on the right. In addition, the content of menu items should flip. Ensure that your CSS accounts for this.

Name	Type	Description
`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.

'press' | 'longPress'

Properties

Name	Type	Description
`focusStrategy`	`FocusStrategy`	Controls which item will be auto focused when the menu opens.
`isOpen`	`boolean`	Whether the overlay is currently open.

Methods

Method	Description
`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.

'first' | 'last'

Name	Type	Description
`current`	`T`

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

Name	Type	Default	Description
`isDisabled`	`boolean`	—	Whether the button is disabled.
`children`	`ReactNode`	—	The content to display in the button.
`onPress`	`( (e: PressEvent )) => void`	—	Handler that is called when the press is released over the target.
`onPressStart`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction starts.
`onPressEnd`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressChange`	`( (isPressed: boolean )) => void`	—	Handler that is called when the press state changes.
`onPressUp`	`( (e: PressEvent )) => void`	—	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`href`	`string`	—	A URL to link to if elementType="a".
`target`	`string`	—	The target window for the link.
`rel`	`string`	—	The relationship between the linked resource and the current page. See MDN.
`elementType`	`ElementType \| JSXElementConstructor<any>`	`'button'`	The HTML element or React element used to render the button, e.g. 'div', 'a', or `RouterLink`.
`aria-expanded`	`boolean \| 'true' \| 'false'`	—	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
`aria-haspopup`	`boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog' \| 'true' \| 'false'`	—	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`aria-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-pressed`	`boolean \| 'true' \| 'false' \| 'mixed'`	—	Indicates the current "pressed" state of toggle buttons.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	The behavior of the button when used in an HTML form.
`preventFocusOnPress`	`boolean`	—	Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`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.

Properties

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`	`Element`	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.
`x`	`number`	X position relative to the target.
`y`	`number`	Y position relative to the target.

Methods

Method	Description
`continuePropagation(): void`	By default, press events stop propagation to parent elements. In cases where a handler decides not to handle a specific event, it can call `continuePropagation()` to allow a parent to handle it.

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

BaseEvent<ReactKeyboardEvent<any>>

SyntheticEvent & {stopPropagation: () => void,
continuePropagation: () => void
}

Name	Type	Description
`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.
`onClose`	`() => void`	Handler that is called when the menu should close after selecting an item.
`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 )) => void`	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.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	Handler that is called when a key is released.

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

string | number

'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.
`setExpandedKeys( (keys: Set<Key> )): void`	Replaces the set of expanded keys.

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

Extends: Iterable

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 \| null`	Get an item by its key.
`at( (idx: number )): T \| null`	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.
`getChildren( (key: Key )): Iterable<T>`	Iterate over the child items of the given key.
`getTextValue( (key: Key )): string`	Returns a string representation of the item's contents.

Name	Type	Description
`type`	`string`	The type of item this node represents.
`key`	`Key`	A unique key for the node.
`value`	`T \| null`	The object value the node was created from.
`level`	`number`	The level of depth this node is at in the hierarchy.
`hasChildNodes`	`boolean`	Whether this item has children, even if not loaded yet.
`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 \| null`	The key of the parent node.
`prevKey`	`Key \| null`	The key of the node before this node.
`nextKey`	`Key \| null`	The key of the node after this node.
`props`	`any`	Additional properties specific to a particular node type.
`render`	`( (node: Node<any> )) => ReactElement`	A function that renders this node to a React Element in the DOM.

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`
`disabledKeys`	`Set<Key>`
`disabledBehavior`	`DisabledBehavior`

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 \| \| null, , 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`
`isDisabled( (key: Key )): void`
`isLink( (key: Key )): void`
`getItemProps( (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.
`disabledBehavior`	`DisabledBehavior`	Whether `disabledKeys` applies to selection, actions, or both.
`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 \| \| null, , child?: FocusStrategy )): void`	Sets the focused key, and optionally, whether the first or last child of that key should receive focus.

'toggle' | 'replace'

'selection' | 'all'

A LayoutDelegate provides layout information for collection items.

Method	Description
`getItemRect( (key: Key )): Rect \| null`	Returns a rectangle for the item with the given key.
`getVisibleRect(): Rect`	Returns the visible rectangle of the collection.
`getContentSize(): Size`	Returns the size of the scrollable content in the collection.
`getKeyRange( (from: Key, , to: Key )): Key[]`	Returns a list of keys between `from` and `to`.

Name	Type	Description
`x`	`number`
`y`	`number`
`width`	`number`
`height`	`number`

Name	Type	Description
`width`	`number`
`height`	`number`

Name	Type	Description
`allowsCellSelection`	`boolean`
`layoutDelegate`	`LayoutDelegate`

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`	`Element`	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.
`x`	`number`	X position relative to the target.
`y`	`number`	Y position relative to the target.

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

All DOM attributes supported across both HTML and SVG elements.

Extends: AriaAttributes, ReactDOMAttributes

Name	Type	Description
`id`	`string \| undefined`
`role`	`AriaRole \| undefined`
`tabIndex`	`number \| undefined`
`style`	`CSSProperties \| undefined`
`className`	`string \| undefined`

Name	Type	Default	Description
`aria-label`	`string`	—	A screen reader only label for the menu item.
`key`	`Key`	—	The unique key for the menu 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.
`aria-haspopup`	`'menu' \| 'dialog'`	—	What kind of popup the item opens.
`aria-expanded`	`boolean \| 'true' \| 'false'`	—	Indicates whether the menu item's popup element is expanded or collapsed.
`aria-controls`	`string`	—	Identifies the menu item's popup element whose contents or presence is controlled by the menu item.
`id`	`string`	—	The element's unique identifier. See MDN.
`onPress`	`( (e: PressEvent )) => void`	—	Handler that is called when the press is released over the target.
`onPressStart`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction starts.
`onPressEnd`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressChange`	`( (isPressed: boolean )) => void`	—	Handler that is called when the press state changes.
`onPressUp`	`( (e: PressEvent )) => void`	—	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`onHoverStart`	`( (e: HoverEvent )) => void`	—	Handler that is called when a hover interaction starts.
`onHoverEnd`	`( (e: HoverEvent )) => void`	—	Handler that is called when a hover interaction ends.
`onHoverChange`	`( (isHovering: boolean )) => void`	—	Handler that is called when the hover state changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.

Name	Type	Description
`type`	`'hoverstart' \| 'hoverend'`	The type of hover event being fired.
`pointerType`	`'mouse' \| 'pen'`	The pointer type that triggered the hover event.
`target`	`HTMLElement`	The target element of the hover event.

Name	Type	Description
`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.
`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.

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`	`DOMAttributes`	Props for the wrapper list item.
`headingProps`	`DOMAttributes`	Props for the heading element, if any.
`groupProps`	`DOMAttributes`	Props for the group element.

Manages state for a menu trigger. Tracks whether the menu is currently open, and controls which item will receive focus when it opens. Also tracks the open submenus within the menu tree via their trigger keys.

useMenuTriggerState(
  (props: MenuTriggerProps
)): RootMenuTriggerState

Name	Type	Default	Description
`trigger`	`MenuTriggerType`	`'press'`	How the menu is triggered.
`isOpen`	`boolean`	—	Whether the overlay is open by default (controlled).
`defaultOpen`	`boolean`	—	Whether the overlay is open by default (uncontrolled).
`onOpenChange`	`( (isOpen: boolean )) => void`	—	Handler that is called when the overlay's open state changes.

Properties

Name	Type	Description
`openSubmenu`	`( (triggerKey: Key, , level: number )) => void`	Opens a specific submenu tied to a specific menu item at a specific level.
`closeSubmenu`	`( (triggerKey: Key, , level: number )) => void`	Closes a specific submenu tied to a specific menu item at a specific level.
`expandedKeysStack`	`Key[]`	An array of open submenu trigger keys within the menu tree. The index of key within array matches the submenu level in the tree.
`close`	`() => void`	Closes the menu and all submenus in the menu tree.
`focusStrategy`	`FocusStrategy`	Controls which item will be auto focused when the menu opens.
`isOpen`	`boolean`	Whether the overlay is currently open.

Methods

Method	Description
`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.

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 extends object>(
  (props: TreeProps<T>
)): TreeState<T>

Name	Type	Description
`disabledBehavior`	`DisabledBehavior`	Whether `disabledKeys` applies to all interactions, or only selection.
`collection`	`Collection<Node<T>>`	A pre-constructed collection to use instead of building one from items and children.
`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 )) => void`	Handler that is called when the selection changes.
`disabledKeys`	`Iterable<Key>`	The currently disabled keys in the collection (controlled).

Provides the behavior and accessibility implementation for a menu trigger.

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

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
    |  | null>
): 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<FocusableElement
    |  | null>
): MenuItemAria

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

useMenuSection(
  (props: AriaMenuSectionProps
)): MenuSectionAria

A RouterProvider accepts a navigate function from a framework or client side router, and provides it to all nested React Aria links to enable client side navigation.

Name	Type	Description
`navigate`	`( (path: Href, , routerOptions: RouterOptions \| \| undefined )) => void`
`children`	`ReactNode`
`useHref`	`( (href: Href )) => string`

RouterConfig extends {href: any
} ? H : string

RouterConfig extends {routerOptions: any
} ? O : never

useMenu

API#

Features#

Anatomy#

Example#

MenuButton#

Menu#

MenuItem#

Popover#

Button#

Styled examples#

Dynamic collections#

Selection#

Sections#

Static items#

Dynamic items#

Accessibility#

Complex menu items#

Disabled items#

Links#

Client side routing#

Controlled open state#

Internationalization#

RTL#

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods