Menu

A menu displays a list of actions or options that a user can choose.

Example#

import {Button, Menu, MenuItem, MenuTrigger, Popover} from 'react-aria-components';

<MenuTrigger>
  <Button aria-label="Menu">☰</Button>
  <Popover>
    <Menu>
      <MenuItem onAction={() => alert('open')}>Open</MenuItem>
      <MenuItem onAction={() => alert('rename')}>Rename…</MenuItem>
      <MenuItem onAction={() => alert('duplicate')}>Duplicate</MenuItem>
      <MenuItem onAction={() => alert('share')}>Share…</MenuItem>
      <MenuItem onAction={() => alert('delete')}>Delete…</MenuItem>
    </Menu>
  </Popover>
</MenuTrigger>

import {
  Button,
  Menu,
  MenuItem,
  MenuTrigger,
  Popover
} from 'react-aria-components';

<MenuTrigger>
  <Button aria-label="Menu">☰</Button>
  <Popover>
    <Menu>
      <MenuItem onAction={() => alert('open')}>
        Open
      </MenuItem>
      <MenuItem onAction={() => alert('rename')}>
        Rename…
      </MenuItem>
      <MenuItem onAction={() => alert('duplicate')}>
        Duplicate
      </MenuItem>
      <MenuItem onAction={() => alert('share')}>
        Share…
      </MenuItem>
      <MenuItem onAction={() => alert('delete')}>
        Delete…
      </MenuItem>
    </Menu>
  </Popover>
</MenuTrigger>

import {
  Button,
  Menu,
  MenuItem,
  MenuTrigger,
  Popover
} from 'react-aria-components';

<MenuTrigger>
  <Button aria-label="Menu">
    ☰
  </Button>
  <Popover>
    <Menu>
      <MenuItem
        onAction={() =>
          alert(
            'open'
          )}
      >
        Open
      </MenuItem>
      <MenuItem
        onAction={() =>
          alert(
            'rename'
          )}
      >
        Rename…
      </MenuItem>
      <MenuItem
        onAction={() =>
          alert(
            'duplicate'
          )}
      >
        Duplicate
      </MenuItem>
      <MenuItem
        onAction={() =>
          alert(
            'share'
          )}
      >
        Share…
      </MenuItem>
      <MenuItem
        onAction={() =>
          alert(
            'delete'
          )}
      >
        Delete…
      </MenuItem>
    </Menu>
  </Popover>
</MenuTrigger>

@import "@react-aria/example-theme";

.react-aria-Menu {
  max-height: inherit;
  box-sizing: border-box;
  overflow: auto;
  padding: 2px;
  min-width: 150px;
  box-sizing: border-box;
  outline: none;
}

.react-aria-MenuItem {
  margin: 2px;
  padding: 0.286rem 0.571rem;
  border-radius: 6px;
  outline: none;
  cursor: default;
  color: var(--text-color);
  font-size: 1.072rem;
  position: relative;
  display: grid;
  grid-template-areas: "label kbd"
                      "desc  kbd";
  align-items: center;
  column-gap: 20px;
  forced-color-adjust: none;

  &[data-focused] {
    background: var(--highlight-background);
    color: var(--highlight-foreground);
  }
}

@import "@react-aria/example-theme";

.react-aria-Menu {
  max-height: inherit;
  box-sizing: border-box;
  overflow: auto;
  padding: 2px;
  min-width: 150px;
  box-sizing: border-box;
  outline: none;
}

.react-aria-MenuItem {
  margin: 2px;
  padding: 0.286rem 0.571rem;
  border-radius: 6px;
  outline: none;
  cursor: default;
  color: var(--text-color);
  font-size: 1.072rem;
  position: relative;
  display: grid;
  grid-template-areas: "label kbd"
                      "desc  kbd";
  align-items: center;
  column-gap: 20px;
  forced-color-adjust: none;

  &[data-focused] {
    background: var(--highlight-background);
    color: var(--highlight-foreground);
  }
}

@import "@react-aria/example-theme";

.react-aria-Menu {
  max-height: inherit;
  box-sizing: border-box;
  overflow: auto;
  padding: 2px;
  min-width: 150px;
  box-sizing: border-box;
  outline: none;
}

.react-aria-MenuItem {
  margin: 2px;
  padding: 0.286rem 0.571rem;
  border-radius: 6px;
  outline: none;
  cursor: default;
  color: var(--text-color);
  font-size: 1.072rem;
  position: relative;
  display: grid;
  grid-template-areas: "label kbd"
                      "desc  kbd";
  align-items: center;
  column-gap: 20px;
  forced-color-adjust: none;

  &[data-focused] {
    background: var(--highlight-background);
    color: var(--highlight-foreground);
  }
}

Features#

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

• Keyboard navigation – Menu items can be navigated using the arrow keys, along with page up/down, home/end, etc. Typeahead, auto scrolling, and disabled items are supported as well.
• Item selection – Single or multiple selection can be optionally enabled.
• Trigger interactions – Menus can be triggered by pressing with a mouse or touch, or optionally, with a long press interaction. The arrow keys also open the menu with a keyboard, automatically focusing the first or last item accordingly.
• Accessible – Follows the ARIA menu pattern, with support for items and sections, and slots for label, description, and keyboard shortcut elements within each item for improved screen reader announcement.

Anatomy#

A menu trigger consists of a button or other trigger element combined with a menu displayed in a popover, with a list of menu items or sections inside. Users can click, touch, or use the keyboard on the button to open the menu.

import {Button, Header, Keyboard, Menu, MenuItem, MenuTrigger, Popover, Section, Separator, Text} from 'react-aria-components';

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

import {
  Button,
  Header,
  Keyboard,
  Menu,
  MenuItem,
  MenuTrigger,
  Popover,
  Section,
  Separator,
  Text
} from 'react-aria-components';

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

import {
  Button,
  Header,
  Keyboard,
  Menu,
  MenuItem,
  MenuTrigger,
  Popover,
  Section,
  Separator,
  Text
} from 'react-aria-components';

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

Concepts#

Menu makes use of the following concepts:

Composed components#

A Menu uses the following components, which may also be used standalone or reused in other components.

Examples#

Action Menu

An animated menu of actions, styled with Tailwind CSS.

Starter kits#

To help kick-start your project, we offer starter kits that include example implementations of all React Aria components with various styling solutions. All components are fully styled, including support for dark mode, high contrast mode, and all UI states. Each starter comes with a pre-configured Storybook that you can experiment with, or use as a starting point for your own component library.

Reusable wrappers#

If you will use a Menu in multiple places in your app, you can wrap all of the pieces into a reusable component. This way, the DOM structure, styling code, and other logic are defined in a single place and reused everywhere to ensure consistency.

This example wraps MenuTrigger and all of its children together into a single component which accepts a label prop and children, which are passed through to the right places. The MenuItem component is also wrapped to apply class names based on the current state, as described in the styling section.

import type {MenuItemProps, MenuProps, MenuTriggerProps} from 'react-aria-components';

interface MyMenuButtonProps<T>
  extends MenuProps<T>, Omit<MenuTriggerProps, 'children'> {
  label?: string;
}

function MyMenuButton<T extends object>(
  { label, children, ...props }: MyMenuButtonProps<T>
) {
  return (
    <MenuTrigger {...props}>
      <Button>{label}</Button>
      <Popover>
        <Menu {...props}>
          {children}
        </Menu>
      </Popover>
    </MenuTrigger>
  );
}

function MyItem(props: MenuItemProps) {
  let textValue = props.textValue ||
    (typeof props.children === 'string' ? props.children : undefined);
  return (
    <MenuItem
      {...props}
      textValue={textValue}
      className={({ isFocused, isSelected, isOpen }) =>
        `my-item ${isFocused ? 'focused' : ''} ${isOpen ? 'open' : ''}`}
    >
      {({ hasSubmenu }) => (
        <>
          {props.children}
          {hasSubmenu && (
            <svg className="chevron" viewBox="0 0 24 24">
              <path d="m9 18 6-6-6-6" />
            </svg>
          )}
        </>
      )}
    </MenuItem>
  );
}

<MyMenuButton label="Edit">
  <MyItem>Cut</MyItem>
  <MyItem>Copy</MyItem>
  <MyItem>Paste</MyItem>
</MyMenuButton>

import type {
  MenuItemProps,
  MenuProps,
  MenuTriggerProps
} from 'react-aria-components';

interface MyMenuButtonProps<T>
  extends MenuProps<T>, Omit<MenuTriggerProps, 'children'> {
  label?: string;
}

function MyMenuButton<T extends object>(
  { label, children, ...props }: MyMenuButtonProps<T>
) {
  return (
    <MenuTrigger {...props}>
      <Button>{label}</Button>
      <Popover>
        <Menu {...props}>
          {children}
        </Menu>
      </Popover>
    </MenuTrigger>
  );
}

function MyItem(props: MenuItemProps) {
  let textValue = props.textValue ||
    (typeof props.children === 'string'
      ? props.children
      : undefined);
  return (
    <MenuItem
      {...props}
      textValue={textValue}
      className={({ isFocused, isSelected, isOpen }) =>
        `my-item ${isFocused ? 'focused' : ''} ${
          isOpen ? 'open' : ''
        }`}
    >
      {({ hasSubmenu }) => (
        <>
          {props.children}
          {hasSubmenu && (
            <svg className="chevron" viewBox="0 0 24 24">
              <path d="m9 18 6-6-6-6" />
            </svg>
          )}
        </>
      )}
    </MenuItem>
  );
}

<MyMenuButton label="Edit">
  <MyItem>Cut</MyItem>
  <MyItem>Copy</MyItem>
  <MyItem>Paste</MyItem>
</MyMenuButton>

import type {
  MenuItemProps,
  MenuProps,
  MenuTriggerProps
} from 'react-aria-components';

interface MyMenuButtonProps<
  T
> extends
  MenuProps<T>,
  Omit<
    MenuTriggerProps,
    'children'
  > {
  label?: string;
}

function MyMenuButton<
  T extends object
>(
  {
    label,
    children,
    ...props
  }: MyMenuButtonProps<T>
) {
  return (
    <MenuTrigger
      {...props}
    >
      <Button>
        {label}
      </Button>
      <Popover>
        <Menu {...props}>
          {children}
        </Menu>
      </Popover>
    </MenuTrigger>
  );
}

function MyItem(
  props: MenuItemProps
) {
  let textValue =
    props.textValue ||
    (typeof props
        .children ===
        'string'
      ? props.children
      : undefined);
  return (
    <MenuItem
      {...props}
      textValue={textValue}
      className={(
        {
          isFocused,
          isSelected,
          isOpen
        }
      ) =>
        `my-item ${
          isFocused
            ? 'focused'
            : ''
        } ${
          isOpen
            ? 'open'
            : ''
        }`}
    >
      {(
        { hasSubmenu }
      ) => (
        <>
          {props
            .children}
          {hasSubmenu &&
            (
              <svg
                className="chevron"
                viewBox="0 0 24 24"
              >
                <path d="m9 18 6-6-6-6" />
              </svg>
            )}
        </>
      )}
    </MenuItem>
  );
}

<MyMenuButton label="Edit">
  <MyItem>Cut</MyItem>
  <MyItem>Copy</MyItem>
  <MyItem>
    Paste
  </MyItem>
</MyMenuButton>

.my-item {
  margin: 2px;
  padding: 0.286rem 0.571rem;
  border-radius: 6px;
  outline: none;
  cursor: default;
  color: var(--text-color);
  font-size: 1.072rem;
  position: relative;

  &.focused {
    background: #e70073;
    color: white;
  }
  &.open:not(.focused) {
    background: rgba(192, 192, 192, 0.3);
    color: var(--text-color);
  }
  .chevron {
    width: 20;
    height: 20;
    fill: none;
    stroke: currentColor;
    stroke-linecap: round;
    stroke-linejoin: round;
    stroke-width: 2;
    position: absolute;
    right: 0;
    top: 0;
    height: 100%;
  }
}

@media (forced-colors: active) {
  .my-item.focused {
    forced-color-adjust: none;
    background: Highlight;
    color: HighlightText;
  }
}

.my-item {
  margin: 2px;
  padding: 0.286rem 0.571rem;
  border-radius: 6px;
  outline: none;
  cursor: default;
  color: var(--text-color);
  font-size: 1.072rem;
  position: relative;

  &.focused {
    background: #e70073;
    color: white;
  }
  &.open:not(.focused) {
    background: rgba(192, 192, 192, 0.3);
    color: var(--text-color);
  }
  .chevron {
    width: 20;
    height: 20;
    fill: none;
    stroke: currentColor;
    stroke-linecap: round;
    stroke-linejoin: round;
    stroke-width: 2;
    position: absolute;
    right: 0;
    top: 0;
    height: 100%;
  }
}

@media (forced-colors: active) {
  .my-item.focused {
    forced-color-adjust: none;
    background: Highlight;
    color: HighlightText;
  }
}

.my-item {
  margin: 2px;
  padding: 0.286rem 0.571rem;
  border-radius: 6px;
  outline: none;
  cursor: default;
  color: var(--text-color);
  font-size: 1.072rem;
  position: relative;

  &.focused {
    background: #e70073;
    color: white;
  }
  &.open:not(.focused) {
    background: rgba(192, 192, 192, 0.3);
    color: var(--text-color);
  }
  .chevron {
    width: 20;
    height: 20;
    fill: none;
    stroke: currentColor;
    stroke-linecap: round;
    stroke-linejoin: round;
    stroke-width: 2;
    position: absolute;
    right: 0;
    top: 0;
    height: 100%;
  }
}

@media (forced-colors: active) {
  .my-item.focused {
    forced-color-adjust: none;
    background: Highlight;
    color: HighlightText;
  }
}

Content#

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 Menu using the items prop. Each item accepts an id prop, which is passed to the onAction prop on the Menu 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 an id 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 (
    <MyMenuButton label="Actions" items={items} onAction={id => alert(id)}>
      {(item) => <MenuItem>{item.name}</MenuItem>}
    </MyMenuButton>
  );
}

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 (
    <MyMenuButton
      label="Actions"
      items={items}
      onAction={(id) => alert(id)}
    >
      {(item) => <MenuItem>{item.name}</MenuItem>}
    </MyMenuButton>
  );
}

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 (
    <MyMenuButton
      label="Actions"
      items={items}
      onAction={(id) =>
        alert(id)}
    >
      {(item) => (
        <MenuItem>
          {item.name}
        </MenuItem>
      )}
    </MyMenuButton>
  );
}

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 id prop of the items.

Single#

import type {Selection} from 'react-aria-components';

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

  return (
    <>
      <MyMenuButton
        label="Align"
        selectionMode="single"
        selectedKeys={selected}
        onSelectionChange={setSelected}
      >
        <MenuItem id="left">Left</MenuItem>
        <MenuItem id="center">Center</MenuItem>
        <MenuItem id="right">Right</MenuItem>
      </MyMenuButton>
      <p>Current selection (controlled): {[...selected].join(', ')}</p>
    </>
  );
}

import type {Selection} from 'react-aria-components';

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

  return (
    <>
      <MyMenuButton
        label="Align"
        selectionMode="single"
        selectedKeys={selected}
        onSelectionChange={setSelected}
      >
        <MenuItem id="left">Left</MenuItem>
        <MenuItem id="center">Center</MenuItem>
        <MenuItem id="right">Right</MenuItem>
      </MyMenuButton>
      <p>
        Current selection (controlled):{' '}
        {[...selected].join(', ')}
      </p>
    </>
  );
}

import type {Selection} from 'react-aria-components';

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

  return (
    <>
      <MyMenuButton
        label="Align"
        selectionMode="single"
        selectedKeys={selected}
        onSelectionChange={setSelected}
      >
        <MenuItem id="left">
          Left
        </MenuItem>
        <MenuItem id="center">
          Center
        </MenuItem>
        <MenuItem id="right">
          Right
        </MenuItem>
      </MyMenuButton>
      <p>
        Current selection
        (controlled):
        {' '}
        {[...selected]
          .join(', ')}
      </p>
    </>
  );
}

.react-aria-MenuItem {
  &[data-selection-mode] {
    padding-left: 24px;

    &::before {
      position: absolute;
      left: 4px;
      font-weight: 600;
    }

    &[data-selection-mode=multiple][data-selected]::before {
      content: '✓';
      content: '✓' / '';
      alt: ' ';
      position: absolute;
      left: 4px;
      font-weight: 600;
    }

    &[data-selection-mode=single][data-selected]::before {
      content: '●';
      content: '●' / '';
      transform: scale(0.7)
    }
  }
}

.react-aria-MenuItem {
  &[data-selection-mode] {
    padding-left: 24px;

    &::before {
      position: absolute;
      left: 4px;
      font-weight: 600;
    }

    &[data-selection-mode=multiple][data-selected]::before {
      content: '✓';
      content: '✓' / '';
      alt: ' ';
      position: absolute;
      left: 4px;
      font-weight: 600;
    }

    &[data-selection-mode=single][data-selected]::before {
      content: '●';
      content: '●' / '';
      transform: scale(0.7)
    }
  }
}

.react-aria-MenuItem {
  &[data-selection-mode] {
    padding-left: 24px;

    &::before {
      position: absolute;
      left: 4px;
      font-weight: 600;
    }

    &[data-selection-mode=multiple][data-selected]::before {
      content: '✓';
      content: '✓' / '';
      alt: ' ';
      position: absolute;
      left: 4px;
      font-weight: 600;
    }

    &[data-selection-mode=single][data-selected]::before {
      content: '●';
      content: '●' / '';
      transform: scale(0.7)
    }
  }
}

Multiple#

import type {Selection} from 'react-aria-components';

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

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

import type {Selection} from 'react-aria-components';

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

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

import type {Selection} from 'react-aria-components';

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

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

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 <MenuItem> component. Link items in a menu are not selectable.

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

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

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

Client side routing#

The <MenuItem> 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.

Sections#

Menu supports sections with headings in order to group items. Sections can be used by wrapping groups of MenuItems in a Section component. A <Header> element may also be included to label the section.

Static items#

import {Section, Header} from 'react-aria-components';

<MyMenuButton label="Actions">
  <Section>
    <Header>Styles</Header>
    <MenuItem>Bold</MenuItem>
    <MenuItem>Underline</MenuItem>
  </Section>
  <Section>
    <Header>Align</Header>
    <MenuItem>Left</MenuItem>
    <MenuItem>Middle</MenuItem>
    <MenuItem>Right</MenuItem>
  </Section>
</MyMenuButton>

import {Section, Header} from 'react-aria-components';

<MyMenuButton label="Actions">
  <Section>
    <Header>Styles</Header>
    <MenuItem>Bold</MenuItem>
    <MenuItem>Underline</MenuItem>
  </Section>
  <Section>
    <Header>Align</Header>
    <MenuItem>Left</MenuItem>
    <MenuItem>Middle</MenuItem>
    <MenuItem>Right</MenuItem>
  </Section>
</MyMenuButton>

import {
  Header,
  Section
} from 'react-aria-components';

<MyMenuButton label="Actions">
  <Section>
    <Header>
      Styles
    </Header>
    <MenuItem>
      Bold
    </MenuItem>
    <MenuItem>
      Underline
    </MenuItem>
  </Section>
  <Section>
    <Header>
      Align
    </Header>
    <MenuItem>
      Left
    </MenuItem>
    <MenuItem>
      Middle
    </MenuItem>
    <MenuItem>
      Right
    </MenuItem>
  </Section>
</MyMenuButton>

.react-aria-Menu {
  .react-aria-Section:not(:first-child) {
    margin-top: 12px;
  }

  .react-aria-Header {
    font-size: 1.143rem;
    font-weight: bold;
    padding: 0 0.714rem;
  }
}

.react-aria-Menu {
  .react-aria-Section:not(:first-child) {
    margin-top: 12px;
  }

  .react-aria-Header {
    font-size: 1.143rem;
    font-weight: bold;
    padding: 0 0.714rem;
  }
}

.react-aria-Menu {
  .react-aria-Section:not(:first-child) {
    margin-top: 12px;
  }

  .react-aria-Header {
    font-size: 1.143rem;
    font-weight: bold;
    padding: 0 0.714rem;
  }
}

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. If the section also has a header, the Collection component can be used to render the child items.

import type {Selection} from 'react-aria-components';
import {Collection} from 'react-aria-components';

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 (
    <MyMenuButton
      label="Window"
      items={openWindows}
      selectionMode="multiple"
      selectedKeys={selected}
      onSelectionChange={setSelected}>
      {section => (
        <Section>
          <Header>{section.name}</Header>
          <Collection items={section.children}>
            {item => <MenuItem>{item.name}</MenuItem>}
          </Collection>
        </Section>
      )}
    </MyMenuButton>
  );
}

import type {Selection} from 'react-aria-components';
import {Collection} from 'react-aria-components';

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 (
    <MyMenuButton
      label="Window"
      items={openWindows}
      selectionMode="multiple"
      selectedKeys={selected}
      onSelectionChange={setSelected}
    >
      {(section) => (
        <Section>
          <Header>{section.name}</Header>
          <Collection items={section.children}>
            {(item) => <MenuItem>{item.name}</MenuItem>}
          </Collection>
        </Section>
      )}
    </MyMenuButton>
  );
}

import type {Selection} from 'react-aria-components';
import {Collection} from 'react-aria-components';

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 (
    <MyMenuButton
      label="Window"
      items={openWindows}
      selectionMode="multiple"
      selectedKeys={selected}
      onSelectionChange={setSelected}
    >
      {(section) => (
        <Section>
          <Header>
            {section
              .name}
          </Header>
          <Collection
            items={section
              .children}
          >
            {(item) => (
              <MenuItem>
                {item
                  .name}
              </MenuItem>
            )}
          </Collection>
        </Section>
      )}
    </MyMenuButton>
  );
}

Separators#

Separators may be added between menu items or sections in order to create non-labeled groupings.

import {Separator} from 'react-aria-components';

<MyMenuButton label="Actions">
  <MenuItem>New…</MenuItem>
  <MenuItem>Open…</MenuItem>
  <Separator />
  <MenuItem>Save</MenuItem>
  <MenuItem>Save as…</MenuItem>
  <MenuItem>Rename…</MenuItem>
  <Separator />
  <MenuItem>Page setup…</MenuItem>
  <MenuItem>Print…</MenuItem>
</MyMenuButton>

import {Separator} from 'react-aria-components';

<MyMenuButton label="Actions">
  <MenuItem>New…</MenuItem>
  <MenuItem>Open…</MenuItem>
  <Separator />
  <MenuItem>Save</MenuItem>
  <MenuItem>Save as…</MenuItem>
  <MenuItem>Rename…</MenuItem>
  <Separator />
  <MenuItem>Page setup…</MenuItem>
  <MenuItem>Print…</MenuItem>
</MyMenuButton>

import {Separator} from 'react-aria-components';

<MyMenuButton label="Actions">
  <MenuItem>
    New…
  </MenuItem>
  <MenuItem>
    Open…
  </MenuItem>
  <Separator />
  <MenuItem>
    Save
  </MenuItem>
  <MenuItem>
    Save as…
  </MenuItem>
  <MenuItem>
    Rename…
  </MenuItem>
  <Separator />
  <MenuItem>
    Page setup…
  </MenuItem>
  <MenuItem>
    Print…
  </MenuItem>
</MyMenuButton>

.react-aria-Menu {
  .react-aria-Separator {
    height: 1px;
    background: var(--border-color);
    margin: 2px 4px;
  }
}

.react-aria-Menu {
  .react-aria-Separator {
    height: 1px;
    background: var(--border-color);
    margin: 2px 4px;
  }
}

.react-aria-Menu {
  .react-aria-Separator {
    height: 1px;
    background: var(--border-color);
    margin: 2px 4px;
  }
}

Accessibility#

Sections without a <Header> must provide an aria-label for accessibility.

Text slots#

By default, items in a ListBox are labeled by their text contents for accessibility. MenuItems also support the "label" and "description" slots to separate primary and secondary content, which improves screen reader announcements and can also be used for styling purposes. The <Keyboard> component can also be used to display a keyboard shortcut.

import {Text, Keyboard} from 'react-aria-components';

<MyMenuButton label="Actions">
  <MenuItem textValue="Copy">
    <Text slot="label">Copy</Text>
    <Text slot="description">Copy the selected text</Text>
    <Keyboard>⌘C</Keyboard>
  </MenuItem>
  <MenuItem textValue="Cut">
    <Text slot="label">Cut</Text>
    <Text slot="description">Cut the selected text</Text>
    <Keyboard>⌘X</Keyboard>
  </MenuItem>
  <MenuItem textValue="Paste">
    <Text slot="label">Paste</Text>
    <Text slot="description">Paste the copied text</Text>
    <Keyboard>⌘V</Keyboard>
  </MenuItem>
</MyMenuButton>

import {Text, Keyboard} from 'react-aria-components';

<MyMenuButton label="Actions">
  <MenuItem textValue="Copy">
    <Text slot="label">Copy</Text>
    <Text slot="description">Copy the selected text</Text>
    <Keyboard>⌘C</Keyboard>
  </MenuItem>
  <MenuItem textValue="Cut">
    <Text slot="label">Cut</Text>
    <Text slot="description">Cut the selected text</Text>
    <Keyboard>⌘X</Keyboard>
  </MenuItem>
  <MenuItem textValue="Paste">
    <Text slot="label">Paste</Text>
    <Text slot="description">Paste the copied text</Text>
    <Keyboard>⌘V</Keyboard>
  </MenuItem>
</MyMenuButton>

import {
  Keyboard,
  Text
} from 'react-aria-components';

<MyMenuButton label="Actions">
  <MenuItem textValue="Copy">
    <Text slot="label">
      Copy
    </Text>
    <Text slot="description">
      Copy the selected
      text
    </Text>
    <Keyboard>
      ⌘C
    </Keyboard>
  </MenuItem>
  <MenuItem textValue="Cut">
    <Text slot="label">
      Cut
    </Text>
    <Text slot="description">
      Cut the selected
      text
    </Text>
    <Keyboard>
      ⌘X
    </Keyboard>
  </MenuItem>
  <MenuItem textValue="Paste">
    <Text slot="label">
      Paste
    </Text>
    <Text slot="description">
      Paste the copied
      text
    </Text>
    <Keyboard>
      ⌘V
    </Keyboard>
  </MenuItem>
</MyMenuButton>

.react-aria-MenuItem {
  [slot=label] {
    font-weight: bold;
    grid-area: label;
  }

  [slot=description] {
    font-size: small;
    grid-area: desc;
  }

  kbd {
    grid-area: kbd;
    font-family: monospace;
    text-align: end;
  }
}

.react-aria-MenuItem {
  [slot=label] {
    font-weight: bold;
    grid-area: label;
  }

  [slot=description] {
    font-size: small;
    grid-area: desc;
  }

  kbd {
    grid-area: kbd;
    font-family: monospace;
    text-align: end;
  }
}

.react-aria-MenuItem {
  [slot=label] {
    font-weight: bold;
    grid-area: label;
  }

  [slot=description] {
    font-size: small;
    grid-area: desc;
  }

  kbd {
    grid-area: kbd;
    font-family: monospace;
    text-align: end;
  }
}

Long press#

By default, MenuTrigger opens by pressing the trigger element or activating it via the Space or Enter keys. However, there may be cases in which your trigger element should perform a separate default action on press, and should only display the Menu when long pressed. This behavior can be changed by providing "longPress" to the trigger prop. With this prop, the Menu will only be opened upon pressing and holding the trigger element or by using the Option (Alt on Windows) + Down Arrow/Up Arrow keys while focusing the trigger element.

<MenuTrigger trigger="longPress">
  <Button onPress={() => alert('crop')}>Crop</Button>
  <Popover>
    <Menu>
      <MenuItem>Rotate</MenuItem>
      <MenuItem>Slice</MenuItem>
      <MenuItem>Clone stamp</MenuItem>
    </Menu>
  </Popover>
</MenuTrigger>

<MenuTrigger trigger="longPress">
  <Button onPress={() => alert('crop')}>Crop</Button>
  <Popover>
    <Menu>
      <MenuItem>Rotate</MenuItem>
      <MenuItem>Slice</MenuItem>
      <MenuItem>Clone stamp</MenuItem>
    </Menu>
  </Popover>
</MenuTrigger>

<MenuTrigger trigger="longPress">
  <Button
    onPress={() =>
      alert('crop')}
  >
    Crop
  </Button>
  <Popover>
    <Menu>
      <MenuItem>
        Rotate
      </MenuItem>
      <MenuItem>
        Slice
      </MenuItem>
      <MenuItem>
        Clone stamp
      </MenuItem>
    </Menu>
  </Popover>
</MenuTrigger>

Disabled items#

A MenuItem can be disabled with the isDisabled prop. Disabled items are not focusable or keyboard navigable, and do not trigger onAction or onSelectionChange.

<MyMenuButton label="Actions">
  <MenuItem>Copy</MenuItem>
  <MenuItem>Cut</MenuItem>
  <MenuItem isDisabled>Paste</MenuItem></MyMenuButton>

<MyMenuButton label="Actions">
  <MenuItem>Copy</MenuItem>
  <MenuItem>Cut</MenuItem>
  <MenuItem isDisabled>Paste</MenuItem></MyMenuButton>

<MyMenuButton label="Actions">
  <MenuItem>
    Copy
  </MenuItem>
  <MenuItem>
    Cut
  </MenuItem>
  <MenuItem isDisabled>
    Paste
  </MenuItem></MyMenuButton>

.react-aria-MenuItem {
  &[data-disabled] {
    color: var(--text-color-disabled);
  }
}

.react-aria-MenuItem {
  &[data-disabled] {
    color: var(--text-color-disabled);
  }
}

.react-aria-MenuItem {
  &[data-disabled] {
    color: var(--text-color-disabled);
  }
}

In dynamic collections, it may be more convenient to use the disabledKeys prop at the Menu level instead of isDisabled on individual items. Each key in this list corresponds with the id prop passed to the MenuItem component, or automatically derived from the values passed to the items prop (see the Collections for more details). An item is considered disabled if its id exists in disabledKeys or if it has isDisabled.

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 (
    <MyMenuButton 
      label="Actions"
      items={items}
      disabledKeys={[4, 6]}    >
      {(item) => <MenuItem>{item.name}</MenuItem>}
    </MyMenuButton>
  );
}

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 (
    <MyMenuButton 
      label="Actions"
      items={items}
      disabledKeys={[4, 6]}    >
      {(item) => <MenuItem>{item.name}</MenuItem>}
    </MyMenuButton>
  );
}

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 (
    <MyMenuButton
      label="Actions"
      items={items}
      disabledKeys={[
        4,
        6
      ]}    >
      {(item) => (
        <MenuItem>
          {item.name}
        </MenuItem>
      )}
    </MyMenuButton>
  );
}

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>
      <MyMenuButton
        label="View"
        isOpen={open}
        onOpenChange={setOpen}>
        <MenuItem id="side">Side bar</MenuItem>
        <MenuItem id="options">Page options</MenuItem>
        <MenuItem id="edit">Edit Panel</MenuItem>
      </MyMenuButton>
    </>
  );
}

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

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

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

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

Submenus#

Submenus can be created by wrapping an item and a submenu in a SubmenuTrigger. The SubmenuTrigger accepts exactly two children: the first child should be the MenuItem which triggers opening of the submenu, and second child should be the Popover containing the submenu.

Static#

import {Menu, Popover, SubmenuTrigger} from 'react-aria-components';

<MyMenuButton label="Actions">
  <MyItem>Cut</MyItem>
  <MyItem>Copy</MyItem>
  <MyItem>Delete</MyItem>
  <SubmenuTrigger>
    <MyItem>Share</MyItem>
    <Popover>
      <Menu>
        <MyItem>SMS</MyItem>
        <MyItem>Twitter</MyItem>
        <SubmenuTrigger>
          <MyItem>Email</MyItem>
          <Popover>
            <Menu>
              <MyItem>Work</MyItem>
              <MyItem>Personal</MyItem>
            </Menu>
          </Popover>
        </SubmenuTrigger>
      </Menu>
    </Popover>
  </SubmenuTrigger>
</MyMenuButton>

import {
  Menu,
  Popover,
  SubmenuTrigger
} from 'react-aria-components';

<MyMenuButton label="Actions">
  <MyItem>Cut</MyItem>
  <MyItem>Copy</MyItem>
  <MyItem>Delete</MyItem>
  <SubmenuTrigger>
    <MyItem>Share</MyItem>
    <Popover>
      <Menu>
        <MyItem>SMS</MyItem>
        <MyItem>Twitter</MyItem>
        <SubmenuTrigger>
          <MyItem>Email</MyItem>
          <Popover>
            <Menu>
              <MyItem>Work</MyItem>
              <MyItem>Personal</MyItem>
            </Menu>
          </Popover>
        </SubmenuTrigger>
      </Menu>
    </Popover>
  </SubmenuTrigger>
</MyMenuButton>

import {
  Menu,
  Popover,
  SubmenuTrigger
} from 'react-aria-components';

<MyMenuButton label="Actions">
  <MyItem>Cut</MyItem>
  <MyItem>Copy</MyItem>
  <MyItem>
    Delete
  </MyItem>
  <SubmenuTrigger>
    <MyItem>
      Share
    </MyItem>
    <Popover>
      <Menu>
        <MyItem>
          SMS
        </MyItem>
        <MyItem>
          Twitter
        </MyItem>
        <SubmenuTrigger>
          <MyItem>
            Email
          </MyItem>
          <Popover>
            <Menu>
              <MyItem>
                Work
              </MyItem>
              <MyItem>
                Personal
              </MyItem>
            </Menu>
          </Popover>
        </SubmenuTrigger>
      </Menu>
    </Popover>
  </SubmenuTrigger>
</MyMenuButton>

Dynamic#

You can define a recursive function to render the nested menu items dynamically.

import {Menu, Popover, SubmenuTrigger} from 'react-aria-components';

let items = [
  {id: 'cut', name: 'Cut'},
  {id: 'copy', name: 'Copy'},
  {id: 'delete', name: 'Delete'},
  {id: 'share', name: 'Share', children: [
    {id: 'sms', name: 'SMS'},
    {id: 'twitter', name: 'Twitter'},
    {id: 'email', name: 'Email', children: [
      {id: 'work', name: 'Work'},
      {id: 'personal', name: 'Personal'},
    ]}
  ]}
];

<MyMenuButton label="Actions" items={items}>
  {function renderSubmenu(item) {
    if (item.children) {
      return (
        <SubmenuTrigger>
          <MyItem key={item.name}>{item.name}</MyItem>
          <Popover>
            <Menu items={item.children}>
              {(item) => renderSubmenu(item)}
            </Menu>
          </Popover>
        </SubmenuTrigger>
      );
    } else {
      return <MyItem key={item.name}>{item.name}</MyItem>;
    }
  }}
</MyMenuButton>

import {
  Menu,
  Popover,
  SubmenuTrigger
} from 'react-aria-components';

let items = [
  { id: 'cut', name: 'Cut' },
  { id: 'copy', name: 'Copy' },
  { id: 'delete', name: 'Delete' },
  {
    id: 'share',
    name: 'Share',
    children: [
      { id: 'sms', name: 'SMS' },
      { id: 'twitter', name: 'Twitter' },
      {
        id: 'email',
        name: 'Email',
        children: [
          { id: 'work', name: 'Work' },
          { id: 'personal', name: 'Personal' }
        ]
      }
    ]
  }
];

<MyMenuButton label="Actions" items={items}>
  {function renderSubmenu(item) {
    if (item.children) {
      return (
        <SubmenuTrigger>
          <MyItem key={item.name}>{item.name}</MyItem>
          <Popover>
            <Menu items={item.children}>
              {(item) => renderSubmenu(item)}
            </Menu>
          </Popover>
        </SubmenuTrigger>
      );
    } else {
      return <MyItem key={item.name}>{item.name}</MyItem>;
    }
  }}
</MyMenuButton>

import {
  Menu,
  Popover,
  SubmenuTrigger
} from 'react-aria-components';

let items = [
  {
    id: 'cut',
    name: 'Cut'
  },
  {
    id: 'copy',
    name: 'Copy'
  },
  {
    id: 'delete',
    name: 'Delete'
  },
  {
    id: 'share',
    name: 'Share',
    children: [
      {
        id: 'sms',
        name: 'SMS'
      },
      {
        id: 'twitter',
        name: 'Twitter'
      },
      {
        id: 'email',
        name: 'Email',
        children: [
          {
            id: 'work',
            name: 'Work'
          },
          {
            id:
              'personal',
            name:
              'Personal'
          }
        ]
      }
    ]
  }
];

<MyMenuButton
  label="Actions"
  items={items}
>
  {function renderSubmenu(
    item
  ) {
    if (
      item.children
    ) {
      return (
        <SubmenuTrigger>
          <MyItem
            key={item
              .name}
          >
            {item.name}
          </MyItem>
          <Popover>
            <Menu
              items={item
                .children}
            >
              {(
                item
              ) =>
                renderSubmenu(
                  item
                )}
            </Menu>
          </Popover>
        </SubmenuTrigger>
      );
    } else {
      return (
        <MyItem
          key={item
            .name}
        >
          {item.name}
        </MyItem>
      );
    }
  }}
</MyMenuButton>

.react-aria-Popover[data-trigger=SubmenuTrigger][data-placement="right"] {
  margin-left: -5px;
}

.react-aria-Popover[data-trigger=SubmenuTrigger][data-placement="left"] {
  margin-right: -5px;
}

.react-aria-Popover[data-trigger=SubmenuTrigger][data-placement="right"] {
  margin-left: -5px;
}

.react-aria-Popover[data-trigger=SubmenuTrigger][data-placement="left"] {
  margin-right: -5px;
}

.react-aria-Popover[data-trigger=SubmenuTrigger][data-placement="right"] {
  margin-left: -5px;
}

.react-aria-Popover[data-trigger=SubmenuTrigger][data-placement="left"] {
  margin-right: -5px;
}

Props#

MenuTrigger#

SubmenuTrigger#

Button#

A <Button> accepts its contents as children. Other props such as onPress and isDisabled will be set by the MenuTrigger.