Design

Interface guidelines Octicons Presentations Command line Mobile Desktop

Build

On this page

ActionList

An ActionList is a list of items that can be activated or selected. ActionList is the base component for many menu-type components, including ActionMenu and SelectPanel.

Beta
Review pending by accessibility team

On this page

github.com/primer
mona
4 vulnerabilities

import {ActionList} from '@primer/react'

Examples

Minimal example

<ActionList>
  <ActionList.Item>New file</ActionList.Item>
  <ActionList.Item>Copy link</ActionList.Item>
  <ActionList.Item>Edit file</ActionList.Item>
  <ActionList.Divider />
  <ActionList.Item variant="danger">Delete file</ActionList.Item>
</ActionList>

<ActionList>
  <ActionList.Item>New file</ActionList.Item>
  <ActionList.Item>Copy link</ActionList.Item>
  <ActionList.Item>Edit file</ActionList.Item>
  <ActionList.Divider />
  <ActionList.Item variant="danger">Delete file</ActionList.Item>
</ActionList>

With leading visual

Leading visuals are optional and appear at the start of an item. They can be octicons, avatars, and other custom visuals that fit a small area.

<ActionList>
  <ActionList.Item>
    <ActionList.LeadingVisual><LinkIcon /></ActionList.LeadingVisual>
    github.com/primer
  </ActionList.Item>
  <ActionList.Item variant="danger">
    <ActionList.LeadingVisual><AlertIcon /></ActionList.LeadingVisual>
    4 vulnerabilities
  </ActionList.Item>
  <ActionList.Item>
    <ActionList.LeadingVisual><Avatar src="https://github.com/mona.png" /></ActionList.LeadingVisual>
    mona
  </ActionList.Item>
</ActionList>

<ActionList>
  <ActionList.Item>
    <ActionList.LeadingVisual><LinkIcon /></ActionList.LeadingVisual>
    github.com/primer
  </ActionList.Item>
  <ActionList.Item variant="danger">
    <ActionList.LeadingVisual><AlertIcon /></ActionList.LeadingVisual>
    4 vulnerabilities
  </ActionList.Item>
  <ActionList.Item>
    <ActionList.LeadingVisual><Avatar src="https://github.com/mona.png" /></ActionList.LeadingVisual>
    mona
  </ActionList.Item>
</ActionList>

With trailing visual

Trailing visual and trailing text can display auxiliary information. They're placed at the right of the item, and can denote status, keyboard shortcuts, or be used to set expectations about what the action does.

<ActionList>
  <ActionList.Item>
    New file
    <ActionList.TrailingVisual>⌘ + N</ActionList.TrailingVisual>
  </ActionList.Item>
  <ActionList.Item>
    Copy link
    <ActionList.TrailingVisual>⌘ + C</ActionList.TrailingVisual>
  </ActionList.Item>
  <ActionList.Item>
    Edit file
    <ActionList.TrailingVisual>⌘ + E</ActionList.TrailingVisual>
  </ActionList.Item>
  <ActionList.Item variant="danger">
    Delete file
    <ActionList.TrailingVisual>⌫</ActionList.TrailingVisual>
  </ActionList.Item>
</ActionList>

<ActionList>
  <ActionList.Item>
    New file
    <ActionList.TrailingVisual>⌘ + N</ActionList.TrailingVisual>
  </ActionList.Item>
  <ActionList.Item>
    Copy link
    <ActionList.TrailingVisual>⌘ + C</ActionList.TrailingVisual>
  </ActionList.Item>
  <ActionList.Item>
    Edit file
    <ActionList.TrailingVisual>⌘ + E</ActionList.TrailingVisual>
  </ActionList.Item>
  <ActionList.Item variant="danger">
    Delete file
    <ActionList.TrailingVisual>⌫</ActionList.TrailingVisual>
  </ActionList.Item>
</ActionList>

With description and dividers

Item dividers allow users to parse heavier amounts of information. They're placed between items and are useful in complex lists, particularly when descriptions or multi-line text is present.

<ActionList showDividers>
  <ActionList.Item>
    <ActionList.LeadingVisual>
      <Avatar src="https://github.com/mona.png" />
    </ActionList.LeadingVisual>
    mona
    <ActionList.Description>Monalisa Octocat</ActionList.Description>
  </ActionList.Item>
  <ActionList.Item>
    <ActionList.LeadingVisual>
      <Avatar src="https://github.com/hubot.png" />
    </ActionList.LeadingVisual>
    hubot
    <ActionList.Description>Hubot</ActionList.Description>
  </ActionList.Item>
  <ActionList.Item>
    <ActionList.LeadingVisual>
      <Avatar src="https://github.com/primer-css.png" />
    </ActionList.LeadingVisual>
    primer-css
    <ActionList.Description>GitHub Design Systems Bot</ActionList.Description>
  </ActionList.Item>
</ActionList>

<ActionList showDividers>
  <ActionList.Item>
    <ActionList.LeadingVisual>
      <Avatar src="https://github.com/mona.png" />
    </ActionList.LeadingVisual>
    mona
    <ActionList.Description>Monalisa Octocat</ActionList.Description>
  </ActionList.Item>
  <ActionList.Item>
    <ActionList.LeadingVisual>
      <Avatar src="https://github.com/hubot.png" />
    </ActionList.LeadingVisual>
    hubot
    <ActionList.Description>Hubot</ActionList.Description>
  </ActionList.Item>
  <ActionList.Item>
    <ActionList.LeadingVisual>
      <Avatar src="https://github.com/primer-css.png" />
    </ActionList.LeadingVisual>
    primer-css
    <ActionList.Description>GitHub Design Systems Bot</ActionList.Description>
  </ActionList.Item>
</ActionList>

With links

When you want to add links to the List instead of actions, use ActionList.LinkItem

<ActionList>
  <ActionList.LinkItem href="https://github.com/primer">
    <ActionList.LeadingVisual>
      <LinkIcon />
    </ActionList.LeadingVisual>
    github/primer
  </ActionList.LinkItem>
  <ActionList.LinkItem as={ReactRouterLink} to="/">
    <ActionList.LeadingVisual>
      <LawIcon />
    </ActionList.LeadingVisual>
    MIT License
  </ActionList.LinkItem>
  <ActionList.LinkItem 
    href="https://github.com/primer/react/stargazers"
    target="_blank"
    rel="noopener noreferrer"
  >
    <ActionList.LeadingVisual>
      <StarIcon />
    </ActionList.LeadingVisual>
    1.4k stars
  </ActionList.LinkItem>
</ActionList>

<ActionList>
  <ActionList.LinkItem href="https://github.com/primer">
    <ActionList.LeadingVisual>
      <LinkIcon />
    </ActionList.LeadingVisual>
    github/primer
  </ActionList.LinkItem>
  <ActionList.LinkItem as={ReactRouterLink} to="/">
    <ActionList.LeadingVisual>
      <LawIcon />
    </ActionList.LeadingVisual>
    MIT License
  </ActionList.LinkItem>
  <ActionList.LinkItem 
    href="https://github.com/primer/react/stargazers"
    target="_blank"
    rel="noopener noreferrer"
  >
    <ActionList.LeadingVisual>
      <StarIcon />
    </ActionList.LeadingVisual>
    1.4k stars
  </ActionList.LinkItem>
</ActionList>

With groups

const SelectFields = () => {
  const [options, setOptions] = React.useState([
    {text: 'Status', selected: true},
    {text: 'Stage', selected: true},
    {text: 'Assignee', selected: true},
    {text: 'Team', selected: true},
    {text: 'Estimate', selected: false},
    {text: 'Due Date', selected: false}
  ])

  const visibleOptions = options.filter(option => option.selected)
  const hiddenOptions = options.filter(option => !option.selected)

  const toggle = text => {
    setOptions(
      options.map(option => {
        if (option.text === text) option.selected = !option.selected
        return option
      })
    )
  }

  return (
    <ActionList selectionVariant="multiple">
      <ActionList.Group title="Visible fields">
        {visibleOptions.map(option => (
          <ActionList.Item key={option.text} selected={true} onSelect={() => toggle(option.text)}>
            {option.text}
          </ActionList.Item>
        ))}
      </ActionList.Group>
      <ActionList.Group
        title="Hidden fields"
        selectionVariant={
          /** selectionVariant override on Group: disable selection if there are no options */
          hiddenOptions.length ? 'multiple' : false
        }
      >
        {hiddenOptions.map((option, index) => (
          <ActionList.Item key={option.text} selected={false} onSelect={() => toggle(option.text)}>
            {option.text}
          </ActionList.Item>
        ))}
        {hiddenOptions.length === 0 && <ActionList.Item disabled>No hidden fields</ActionList.Item>}
      </ActionList.Group>
    </ActionList>
  )
}

render(<SelectFields />)

const SelectFields = () => {
  const [options, setOptions] = React.useState([
    {text: 'Status', selected: true},
    {text: 'Stage', selected: true},
    {text: 'Assignee', selected: true},
    {text: 'Team', selected: true},
    {text: 'Estimate', selected: false},
    {text: 'Due Date', selected: false}
  ])

  const visibleOptions = options.filter(option => option.selected)
  const hiddenOptions = options.filter(option => !option.selected)

  const toggle = text => {
    setOptions(
      options.map(option => {
        if (option.text === text) option.selected = !option.selected
        return option
      })
    )
  }

  return (
    <ActionList selectionVariant="multiple">
      <ActionList.Group title="Visible fields">
        {visibleOptions.map(option => (
          <ActionList.Item key={option.text} selected={true} onSelect={() => toggle(option.text)}>
            {option.text}
          </ActionList.Item>
        ))}
      </ActionList.Group>
      <ActionList.Group
        title="Hidden fields"
        selectionVariant={
          /** selectionVariant override on Group: disable selection if there are no options */
          hiddenOptions.length ? 'multiple' : false
        }
      >
        {hiddenOptions.map((option, index) => (
          <ActionList.Item key={option.text} selected={false} onSelect={() => toggle(option.text)}>
            {option.text}
          </ActionList.Item>
        ))}
        {hiddenOptions.length === 0 && <ActionList.Item disabled>No hidden fields</ActionList.Item>}
      </ActionList.Group>
    </ActionList>
  )
}

render(<SelectFields />)

Props

ActionList

Name	Type	Default	Description
children Required	ActionList.Item[] \| ActionList.LinkItem[] \| ActionList.Group[]
variant	'inset' \| 'full'	'inset'	`inset` children are offset (vertically and horizontally) from list edges. `full` children are flush (vertically and horizontally) with list edges
selectionVariant	'single' \| 'multiple'		Whether multiple items or a single item can be selected.
showDivider	boolean	false	Display a divider above each item in this list when it does not follow a header or divider.
role	AriaRole		ARIA role describing the function of the list. `listbox` and `menu` are a common values.
sx	SystemStyleObject		Style overrides to apply to the component. See also overriding styles.

ActionList.Item

Name	Type	Default	Description
children Required	React.ReactNode \| ActionList.LeadingVisual \| ActionList.Description \| ActionList.TrailingVisual
variant	'default' \| 'danger'	'default'	`danger` indicates that the item is destructive.
onSelect	(event: React.MouseEvent<HTMLLIElement> \| React.KeyboardEvent<HTMLLIElement>) => void		Callback that is called when the item is selected using either the mouse or keyboard.
selected	boolean	false	Indicate whether the item is selected. Only applies to items that can be selected.
active	boolean	false	Indicate whether the item is active. There should never be more than one active item.
disabled	boolean	false	Items that are disabled can not be clicked, selected, or navigated to.
role	AriaRole		ARIA role describing the function of the item. `option` is a common value.
sx	SystemStyleObject		Style overrides to apply to the component. See also overriding styles.

ActionList.LinkItem

Name	Type	Default	Description
children Required	React.ReactNode \| ActionList.LeadingVisual \| ActionList.Description \| ActionList.TrailingVisual
active	boolean	false	Indicate whether the item is active. There should never be more than one active item.
sx	SystemStyleObject		Style overrides to apply to the component. See also overriding styles.
as	React.ElementType	"a"	The underlying element to render — either a HTML element name or a React component.
ref	React.RefObject<HTMLAnchorElement>		A ref to the element rendered by this component. Because this component is polymorphic, the type will vary based on the value of the `as` prop.
Additional props are passed to the `<a>` element. See MDN for a list of props accepted by the `<a>` element. If an `as` prop is specified, the accepted props will change accordingly.

ActionList.LeadingVisual

Name	Type	Default	Description
children Required	React.ReactNode		Icon (or similar) positioned before item text.
sx	SystemStyleObject		Style overrides to apply to the component. See also overriding styles.

ActionList.TrailingVisual

Name	Type	Default	Description
children Required	React.ReactNode		Visual positioned after item text.
sx	SystemStyleObject		Style overrides to apply to the component. See also overriding styles.

ActionList.Description

Name	Type	Default	Description
children Required	React.ReactNode
variant	'inline' \| 'block'	'inline'	`inline` descriptions are positioned beside primary text. `block` descriptions are positioned below primary text.
sx	SystemStyleObject		Style overrides to apply to the component. See also overriding styles.

ActionList.Group

Name	Type	Default	Description
children Required	ActionList.Item[] \| ActionList.LinkItem[]
title	string		Title of the group.
auxiliaryText	string		Secondary text that provides additional information about the group.
variant	'filled' \| 'subtle'	'subtle'	`inline` descriptions are positioned beside primary text. `block` descriptions are positioned below primary text.
selectionVariant	'single' \| 'multiple' \| false		Set `selectionVariant` at the group level.
role	AriaRole		ARIA role describing the function of the list inside the group. `listbox` and `menu` are a common values.
sx	SystemStyleObject		Style overrides to apply to the component. See also overriding styles.

Status

Alpha

Component props are documented on primer.style/react.
Component does not have any unnecessary third-party dependencies.
Component can adapt to different themes.
Component can adapt to different screen sizes.
Component has 100% test coverage.

Beta

Component is used in a production application.
Common usage examples are documented on primer.style/react.
Common usage examples are documented in storybook stories.
Component has been reviewed by a systems designer and any resulting issues have been addressed.
Component has been manually reviewed by the accessibility team and any resulting issues have been addressed.

Stable

Component API has been stable with no breaking changes for at least one month.
Feedback on API usability has been sought from developers using the component and any resulting issues have been addressed.
Component has corresponding design guidelines documented in the interface guidelines.
Component has corresponding Figma component in the Primer Web library.

ActionList

Examples

Minimal example

With leading visual

With trailing visual

With description and dividers

With links

With groups

Props

ActionList

ActionList.Item

ActionList.LinkItem

ActionList.LeadingVisual

ActionList.TrailingVisual

ActionList.Description

ActionList.Group

Status

Alpha

Beta

Stable

Further reading

Related components