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.

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>
  );
}

Use when the items benefit from an associated action or image, such as a list of products.

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

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

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

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

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

Use when the items benefit from an associated action or image, such as a list of products.

import {Button, Popover, ActionList, Icon} from '@shopify/polaris';
import {ImportMinor, TickSmallMinor, ExportMinor} from '@shopify/polaris-icons';
import {useState, useCallback} from 'react';

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

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

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

  return (
    <div style={{height: '200px'}}>
      <Popover
        active={active}
        activator={activator}
        autofocusTarget="first-node"
        onClose={toggleActive}
      >
        <ActionList
          actionRole="menuitem"
          items={[
            {
              active: true,
              content: 'Import file',
              icon: ImportMinor,
              suffix: <Icon source={TickSmallMinor} />,
            },
            {content: 'Export file', icon: ExportMinor},
          ]}
        />
      </Popover>
    </div>
  );
}

Use when the items benefit from sections to help differentiate actions.

import {Button, Popover, ActionList} from '@shopify/polaris';
import {
  ImportMinor,
  ExportMinor,
  EditMinor,
  DeleteMinor,
} from '@shopify/polaris-icons';
import {useState, useCallback} from 'react';

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

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

  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"
          sections={[
            {
              title: 'File options',
              items: [
                {content: 'Import file', icon: ImportMinor},
                {content: 'Export file', icon: ExportMinor},
              ],
            },
            {
              title: 'Bulk actions',
              items: [
                {content: 'Edit', icon: EditMinor},
                {content: 'Delete', icon: DeleteMinor},
              ],
            },
          ]}
        />
      </Popover>
    </div>
  );
}

Use to visually indicate that an action list item is destructive.

import {Button, Popover, ActionList} from '@shopify/polaris';
import {ImportMinor, ExportMinor, DeleteMinor} from '@shopify/polaris-icons';
import {useState, useCallback} from 'react';

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

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

  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"
          sections={[
            {
              title: 'File options',
              items: [
                {
                  active: true,
                  content: 'Import file',
                  icon: ImportMinor,
                },
                {content: 'Export file', icon: ExportMinor},
                {
                  destructive: true,
                  content: 'Delete file',
                  icon: DeleteMinor,
                },
              ],
            },
          ]}
        />
      </Popover>
    </div>
  );
}

Use help text when the normal Verb noun syntax for the actions does not provide sufficient context for the merchant.

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

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

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

  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"
          sections={[
            {
              items: [
                {
                  content: 'Blog posts',
                  helpText: 'Manage your blog articles',
                },
                {
                  content: 'Blogs',
                  helpText: 'Manage blogs published to your Online Store',
                },
              ],
            },
          ]}
        />
      </Popover>
    </div>
  );
}

Use help text when the normal Verb noun syntax for the actions does not provide sufficient context for the merchant.

import {ActionList, Thumbnail, Icon, Avatar} from '@shopify/polaris';
import {ChevronRightMinor} from '@shopify/polaris-icons';
import React from 'react';

function ActionListWithPrefixSuffixExample() {
  return (
    <div style={{height: '250px', maxWidth: '350px'}}>
      <ActionList
        actionRole="menuitem"
        items={[
          {
            content: 'Go here',
            prefix: (
              <Thumbnail
                source="https://burst.shopifycdn.com/photos/black-leather-choker-necklace_373x@2x.jpg"
                size="small"
                alt="Black leather pet collar"
              />
            ),
            suffix: <Icon source={ChevronRightMinor} />,
          },
          {
            content: 'Or there',
            prefix: <Avatar customer name="Farrah" size="small" />,
            suffix: <Icon source={ChevronRightMinor} />,
          },
        ]}
      />
    </div>
  );
}

Props

Want to help make this feature better? Please share your feedback.

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.

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


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