Skip to contentShopify logoPolaris

Action list

Action lists render a list of actions or selectable options. This component is usually placed inside a popover container to create a dropdown menu or to let merchants select from a list of options.

Action list component examples

Use for the least important actions so merchants aren’t distracted by secondary tasks. Can also be used for a set of actions that won’t fit in the available screen space.

import {Button, Popover, ActionList} from '@shopify/polaris';
import {useState, useCallback} from 'react';

function ActionListInPopoverExample() {
  const [active, setActive] = useState(true);

  const toggleActive = useCallback(() => setActive((active) => !active), []);

  const handleImportedAction = useCallback(
    () => console.log('Imported action'),
    [],
  );

  const handleExportedAction = useCallback(
    () => console.log('Exported action'),
    [],
  );

  const activator = (
    <Button onClick={toggleActive} disclosure>
      More actions
    </Button>
  );

  return (
    <div style={{height: '250px'}}>
      <Popover
        active={active}
        activator={activator}
        autofocusTarget="first-node"
        onClose={toggleActive}
      >
        <ActionList
          actionRole="menuitem"
          items={[
            {
              content: 'Import file',
              onAction: handleImportedAction,
            },
            {
              content: 'Export file',
              onAction: handleExportedAction,
            },
          ]}
        />
      </Popover>
    </div>
  );
}

Props

interface ActionListProps
items?readonly []

Collection of actions for list.

sections?readonly []

Collection of sectioned action items.

actionRole?string

Defines a specific role attribute for each action in the list.

allowFiltering?boolean

Allow users to filter items in the list. Will only show if more than 8 items in the list. The item content of every items must be a string for this to work.

filterLabel?string

Filter label used as a placeholder in the search field.

onActionAnyItem?() => void

Callback when any item is clicked or keypressed.

Best practices

Actions lists should:

  • Be used for secondary or less important information and actions since they’re hidden until merchants expose them by opening a popover
  • Contain actions that are related to each other

Content guidelines

Action lists

Each item in an action list should be clear and predictable. Merchants should be able to anticipate what will happen when they click on an action item.

Do

Buy shipping label

Don't

Buy

Each item in an action list should always lead with a strong verb that encourages action. To provide enough context use the {verb}+{noun} format unless the action is clear with a single verb.

Do
  • Rename
  • Edit HTML
Don't
  • File name changes
  • HTML editing options

Each item in an action list should be scannable avoiding unnecessary words and articles such as the, an, or a.

Do
  • Add menu item
Don't
  • Add a menu item

Related components

Accessibility

Items in an action list are organized as list items (<li>) in an unordered list (<ul>) and are conveyed as a group of related elements to assistive technology users. Each item is implemented as a button.

Keyboard support

  • Give the action list items keyboard focus with the tab key (or shift + tab when tabbing backwards)
  • When action list items have a role of menuitem, navigate through the list with down arrow (up arrow to move backwards)
  • Activate buttons with the enter/return key or the space key

High contrast support

  • Each item is clearly discernible in high contrast mode
  • Each item that is focused and hovered is clearly discernible in high contrast mode

    On this page