ActionMenu

Convenience component to display an ActionButton with a Menu.

install	`yarn add @react-spectrum/menu`
version	3.4.0
usage	`import {ActionMenu} from '@react-spectrum/menu'`

View guidelines

Spectrum

Example#

<ActionMenu>
  <Item>Cut</Item>
  <Item>Copy</Item>
  <Item>Paste</Item>
</ActionMenu>

<ActionMenu>
  <Item>Cut</Item>
  <Item>Copy</Item>
  <Item>Paste</Item>
</ActionMenu>

<ActionMenu>
  <Item>Cut</Item>
  <Item>Copy</Item>
  <Item>Paste</Item>
</ActionMenu>

Content#

ActionMenu follows the Collection Components API, accepting both static and dynamic collections. See Menu for further explanation.

function Example() {
  let actionMenuItems = [
    {name: 'Cut'},
    {name: 'Copy'},
    {name: 'Paste'},
    {name: 'Replace'}
  ];

  return (
    <ActionMenu items={actionMenuItems}>
      {(item) => <Item key={item.name}>{item.name}</Item>}
    </ActionMenu>
  );
}

function Example() {
  let actionMenuItems = [
    {name: 'Cut'},
    {name: 'Copy'},
    {name: 'Paste'},
    {name: 'Replace'}
  ];

  return (
    <ActionMenu items={actionMenuItems}>
      {(item) => <Item key={item.name}>{item.name}</Item>}
    </ActionMenu>
  );
}

function Example() {
  let actionMenuItems = [
    {name: 'Cut'},
    {name: 'Copy'},
    {name: 'Paste'},
    {name: 'Replace'}
  ];

  return (
    <ActionMenu
      items={
        actionMenuItems
      }>
      {(item) => (
        <Item
          key={
            item.name
          }>
          {item.name}
        </Item>
      )}
    </ActionMenu>
  );
}

Trays#

On mobile, ActionMenus automatically display in a tray instead of a popover to improve usability.

Internationalization#

In order to internationalize an ActionMenu, the content provided to all child items should be localized. For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the ActionMenu is flipped.

Events#

ActionMenu supports the onAction prop, which is called when the user presses a menu item. It receives the key of the item as an argument, which can be used to perform the relevant action.

function Example() {
  let [action, setAction] = React.useState('');

  return (
    <>
      <ActionMenu onAction={setAction}>
        <Item key="cut">Cut</Item>
        <Item key="copy">Copy</Item>
        <Item key="paste">Paste</Item>
      </ActionMenu>
      <p>Action: {action}</p>
    </>
  );
}

function Example() {
  let [action, setAction] = React.useState('');

  return (
    <>
      <ActionMenu onAction={setAction}>
        <Item key="cut">Cut</Item>
        <Item key="copy">Copy</Item>
        <Item key="paste">Paste</Item>
      </ActionMenu>
      <p>Action: {action}</p>
    </>
  );
}

function Example() {
  let [
    action,
    setAction
  ] = React.useState('');

  return (
    <>
      <ActionMenu
        onAction={
          setAction
        }>
        <Item key="cut">
          Cut
        </Item>
        <Item key="copy">
          Copy
        </Item>
        <Item key="paste">
          Paste
        </Item>
      </ActionMenu>
      <p>
        Action: {action}
      </p>
    </>
  );
}

Sections#

ActionMenu supports sections 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.

Static Items#

<ActionMenu>
  <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>
</ActionMenu>

<ActionMenu>
  <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>
</ActionMenu>

<ActionMenu>
  <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>
</ActionMenu>

Dynamic Items#

Sections used with dynamic items are populated from a hierarchical data structure. Similarly to the props on ActionMenu, <Section> takes an array of data using the items prop.

function Example() {
  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 (
    <ActionMenu items={openWindows}>
      {(item) => (
        <Section items={item.children} title={item.name}>
          {(item) => <Item>{item.name}</Item>}
        </Section>
      )}
    </ActionMenu>
  );
}

function Example() {
  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 (
    <ActionMenu items={openWindows}>
      {(item) => (
        <Section items={item.children} title={item.name}>
          {(item) => <Item>{item.name}</Item>}
        </Section>
      )}
    </ActionMenu>
  );
}

function Example() {
  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 (
    <ActionMenu
      items={
        openWindows
      }>
      {(item) => (
        <Section
          items={
            item.children
          }
          title={
            item.name
          }>
          {(item) => (
            <Item>
              {item.name}
            </Item>
          )}
        </Section>
      )}
    </ActionMenu>
  );
}

Accessibility#

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

Items within ActionMenu also allow for additional content used to better communicate options. Icons and descriptions can be added to the children of Item as shown in the example below. If a description is added, the prop slot="description" must be used to distinguish the different <Text> elements.

import {Keyboard, Text} from '@react-spectrum/text';
<ActionMenu>
  <Item key="cut" textValue="cut">
    <Cut size="S" />
    <Text>Cut</Text>
    <Keyboard>⌘X</Keyboard>
  </Item>
  <Item key="copy" textValue="copy">
    <Copy size="S" />
    <Text>Copy</Text>
    <Keyboard>⌘C</Keyboard>
  </Item>
  <Item key="paste" textValue="paste">
    <Paste size="S" />
    <Text>Paste</Text>
    <Keyboard>⌘V</Keyboard>
  </Item>
</ActionMenu>

import {Keyboard, Text} from '@react-spectrum/text';
<ActionMenu>
  <Item key="cut" textValue="cut">
    <Cut size="S" />
    <Text>Cut</Text>
    <Keyboard>⌘X</Keyboard>
  </Item>
  <Item key="copy" textValue="copy">
    <Copy size="S" />
    <Text>Copy</Text>
    <Keyboard>⌘C</Keyboard>
  </Item>
  <Item key="paste" textValue="paste">
    <Paste size="S" />
    <Text>Paste</Text>
    <Keyboard>⌘V</Keyboard>
  </Item>
</ActionMenu>

import {
  Keyboard,
  Text
} from '@react-spectrum/text';
<ActionMenu>
  <Item
    key="cut"
    textValue="cut">
    <Cut size="S" />
    <Text>Cut</Text>
    <Keyboard>
      ⌘X
    </Keyboard>
  </Item>
  <Item
    key="copy"
    textValue="copy">
    <Copy size="S" />
    <Text>Copy</Text>
    <Keyboard>
      ⌘C
    </Keyboard>
  </Item>
  <Item
    key="paste"
    textValue="paste">
    <Paste size="S" />
    <Text>Paste</Text>
    <Keyboard>
      ⌘V
    </Keyboard>
  </Item>
</ActionMenu>

Props#

Name	Type	Default	Description
`children`	`CollectionChildren<T>`	—	The contents of the collection.
`align`	`Alignment`	`'start'`	Alignment of the menu relative to the trigger.
`direction`	`'bottom' \| 'top' \| 'left' \| 'right' \| 'start' \| 'end'`	`'bottom'`	Where the Menu opens relative to its trigger.
`shouldFlip`	`boolean`	`true`	Whether the menu should automatically flip direction when space is limited.
`isDisabled`	`boolean`	—	Whether the button is disabled.
`isQuiet`	`boolean`	—	Whether the button should be displayed with a quiet style.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`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.

Events

Name	Type	Default	Description
`onAction`	`( (key: Key )) => void`	—	Handler that is called when an item is selected.

Accessibility

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

Visual options#

Autofocus#

Applying autoFocus to the ActionMenu sets focus to the ActionMenu trigger.

Disabled items#

<ActionMenu
  items={[
    {name: 'tiff', id: 'a1b2c3'},
    {name: 'png', id: 'g5h1j9'},
    {name: 'jpg', id: 'p8k3i4'},
    {name: 'PDF', id: 'j7i3a0'}
  ]}
  disabledKeys={['a1b2c3', 'p8k3i4']}>
  {(item) => <Item>{item.name}</Item>}
</ActionMenu>

<ActionMenu
  items={[
    {name: 'tiff', id: 'a1b2c3'},
    {name: 'png', id: 'g5h1j9'},
    {name: 'jpg', id: 'p8k3i4'},
    {name: 'PDF', id: 'j7i3a0'}
  ]}
  disabledKeys={['a1b2c3', 'p8k3i4']}>
  {(item) => <Item>{item.name}</Item>}
</ActionMenu>

<ActionMenu
  items={[
    {
      name: 'tiff',
      id: 'a1b2c3'
    },
    {
      name: 'png',
      id: 'g5h1j9'
    },
    {
      name: 'jpg',
      id: 'p8k3i4'
    },
    {
      name: 'PDF',
      id: 'j7i3a0'
    }
  ]}
  disabledKeys={[
    'a1b2c3',
    'p8k3i4'
  ]}>
  {(item) => (
    <Item>
      {item.name}
    </Item>
  )}
</ActionMenu>

Align and direction#