ActionList

ActionList is a vertical list of interactive actions or options. It's composed of items presented in a consistent, single-column format, with room for icons, descriptions, side information, and other rich visuals.

Page navigation navigation

React

readyNot reviewed for a11y

Storybook|Source

Rails

readyReviewed for a11y

Docs|Lookbook|Source

Figma

View in Figma|

React examples

Default

The simplest usage of an ActionList

<ActionList>
  <ActionList.Item>Item one</ActionList.Item>
  <ActionList.Item>Item two</ActionList.Item>
  <ActionList.Item>Item three</ActionList.Item>
</ActionList>

<ActionList>
  <ActionList.Item>Item one</ActionList.Item>
  <ActionList.Item>Item two</ActionList.Item>
  <ActionList.Item>Item three</ActionList.Item>
</ActionList>

Items with leading and trailing content

ActionList items can contain render non-interactive content, typically a visual such as an icon, before or after the item content.

<ActionList>
  <ActionList.Item>
    <ActionList.LeadingVisual>
      <Avatar src="https://github.com/mona.png" />
    </ActionList.LeadingVisual>
    Item one
    <ActionList.TrailingVisual>
      <PencilIcon />
    </ActionList.TrailingVisual>
  </ActionList.Item>
  <ActionList.Item>
    <ActionList.LeadingVisual>
      <Avatar src="https://github.com/mona.png" />
    </ActionList.LeadingVisual>
    Item two
    <ActionList.TrailingVisual>
      <PencilIcon />
    </ActionList.TrailingVisual>
  </ActionList.Item>
  <ActionList.Item>
    <ActionList.LeadingVisual>
      <Avatar src="https://github.com/mona.png" />
    </ActionList.LeadingVisual>
    Item three
    <ActionList.TrailingVisual>
      <PencilIcon />
    </ActionList.TrailingVisual>
  </ActionList.Item>
</ActionList>

<ActionList>
  <ActionList.Item>
    <ActionList.LeadingVisual>
      <Avatar src="https://github.com/mona.png" />
    </ActionList.LeadingVisual>
    Item one
    <ActionList.TrailingVisual>
      <PencilIcon />
    </ActionList.TrailingVisual>
  </ActionList.Item>
  <ActionList.Item>
    <ActionList.LeadingVisual>
      <Avatar src="https://github.com/mona.png" />
    </ActionList.LeadingVisual>
    Item two
    <ActionList.TrailingVisual>
      <PencilIcon />
    </ActionList.TrailingVisual>
  </ActionList.Item>
  <ActionList.Item>
    <ActionList.LeadingVisual>
      <Avatar src="https://github.com/mona.png" />
    </ActionList.LeadingVisual>
    Item three
    <ActionList.TrailingVisual>
      <PencilIcon />
    </ActionList.TrailingVisual>
  </ActionList.Item>
</ActionList>

Items with trailing actions

Similar to a trailing visual, except it triggers a secondary action when activated.

Trailing action guidelines

<ActionList>
  <ActionList.Item>
    Item one
    <ActionList.TrailingAction label="Expand sidebar" icon={ArrowLeftIcon} />
  </ActionList.Item>
  <ActionList.Item>
    Item two (with link TrailingAction)
    <ActionList.TrailingAction as="a" href="#" label="Some action two" icon={ArrowRightIcon} />
  </ActionList.Item>
  <ActionList.Item>
    Item three
    <ActionList.TrailingAction label="Some action three" icon={BookIcon} />
  </ActionList.Item>
</ActionList>

<ActionList>
  <ActionList.Item>
    Item one
    <ActionList.TrailingAction label="Expand sidebar" icon={ArrowLeftIcon} />
  </ActionList.Item>
  <ActionList.Item>
    Item two (with link TrailingAction)
    <ActionList.TrailingAction as="a" href="#" label="Some action two" icon={ArrowRightIcon} />
  </ActionList.Item>
  <ActionList.Item>
    Item three
    <ActionList.TrailingAction label="Some action three" icon={BookIcon} />
  </ActionList.Item>
</ActionList>

Items with dividers

Item dividers guidelines

<ActionList showDividers>
  <ActionList.Item>Item one</ActionList.Item>
  <ActionList.Item>Item two</ActionList.Item>
  <ActionList.Item>Item three</ActionList.Item>
</ActionList>

<ActionList showDividers>
  <ActionList.Item>Item one</ActionList.Item>
  <ActionList.Item>Item two</ActionList.Item>
  <ActionList.Item>Item three</ActionList.Item>
</ActionList>

Items with inline descriptions

<ActionList>
  <ActionList.Item>
    Item one
    <ActionList.Description>Lorem ipsum dolor</ActionList.Description>
  </ActionList.Item>
  <ActionList.Item>
    Item two
    <ActionList.Description>Sit amet consectetur</ActionList.Description>
  </ActionList.Item>
  <ActionList.Item>
    Item three
    <ActionList.Description>Adipiscing elit</ActionList.Description>
  </ActionList.Item>
</ActionList>

<ActionList>
  <ActionList.Item>
    Item one
    <ActionList.Description>Lorem ipsum dolor</ActionList.Description>
  </ActionList.Item>
  <ActionList.Item>
    Item two
    <ActionList.Description>Sit amet consectetur</ActionList.Description>
  </ActionList.Item>
  <ActionList.Item>
    Item three
    <ActionList.Description>Adipiscing elit</ActionList.Description>
  </ActionList.Item>
</ActionList>

Items with block descriptions

<ActionList>
  <ActionList.Item>
    Item one
    <ActionList.Description variant="block">Lorem ipsum dolor</ActionList.Description>
  </ActionList.Item>
  <ActionList.Item>
    Item two
    <ActionList.Description variant="block">Sit amet consectetur</ActionList.Description>
  </ActionList.Item>
  <ActionList.Item>
    Item three
    <ActionList.Description variant="block">Adipiscing elit</ActionList.Description>
  </ActionList.Item>
</ActionList>

<ActionList>
  <ActionList.Item>
    Item one
    <ActionList.Description variant="block">Lorem ipsum dolor</ActionList.Description>
  </ActionList.Item>
  <ActionList.Item>
    Item two
    <ActionList.Description variant="block">Sit amet consectetur</ActionList.Description>
  </ActionList.Item>
  <ActionList.Item>
    Item three
    <ActionList.Description variant="block">Adipiscing elit</ActionList.Description>
  </ActionList.Item>
</ActionList>

With a danger item

A variant used to highlight an action that requires extra attention from the user.

Danger item guidelines

<ActionList>
  <ActionList.Item>Item one</ActionList.Item>
  <ActionList.Item>Item two</ActionList.Item>
  <ActionList.Item>Item three</ActionList.Item>
  <ActionList.Item variant="danger">Delete</ActionList.Item>
</ActionList>

<ActionList>
  <ActionList.Item>Item one</ActionList.Item>
  <ActionList.Item>Item two</ActionList.Item>
  <ActionList.Item>Item three</ActionList.Item>
  <ActionList.Item variant="danger">Delete</ActionList.Item>
</ActionList>

With an inactive item

Inactive items that are non-functional due to some system state such as an outage.

Inactive item guidelines

Item one

<ActionList>
  <ActionList.Item inactiveText="Unavailable due to an outage">Item one</ActionList.Item>
  <ActionList.Item>Item two</ActionList.Item>
  <ActionList.Item>Item three</ActionList.Item>
</ActionList>

<ActionList>
  <ActionList.Item inactiveText="Unavailable due to an outage">Item one</ActionList.Item>
  <ActionList.Item>Item two</ActionList.Item>
  <ActionList.Item>Item three</ActionList.Item>
</ActionList>

With a loading item

Loading item guidelines

<ActionList>
  <ActionList.Item loading>Item one</ActionList.Item>
  <ActionList.Item>Item two</ActionList.Item>
  <ActionList.Item>Item three</ActionList.Item>
</ActionList>

<ActionList>
  <ActionList.Item loading>Item one</ActionList.Item>
  <ActionList.Item>Item two</ActionList.Item>
  <ActionList.Item>Item three</ActionList.Item>
</ActionList>

With a disabled item

<ActionList>
  <ActionList.Item disabled>Item one</ActionList.Item>
  <ActionList.Item>Item two</ActionList.Item>
  <ActionList.Item>Item three</ActionList.Item>
</ActionList>

<ActionList>
  <ActionList.Item disabled>Item one</ActionList.Item>
  <ActionList.Item>Item two</ActionList.Item>
  <ActionList.Item>Item three</ActionList.Item>
</ActionList>

Single-select

Selection state guidelines

import React from 'react'
import {ActionList} from '@primer/react'


const items = [{label: 'Item one'}, {label: 'Item two'}, {label: 'Item three'}]


export default function SingleSelect() {
  const [selectedIndex, setSelectedIndex] = React.useState(0)


  return (
    <ActionList selectionVariant="single" role="menu" aria-label="Item">
      {items.map((item, index) => (
        <ActionList.Item
          key={index}
          role="menuitemradio"
          selected={index === selectedIndex}
          aria-checked={index === selectedIndex}
          onSelect={() => setSelectedIndex(index)}
        >
          {item.label}
        </ActionList.Item>
      ))}
    </ActionList>
  )
}

import React from 'react'
import {ActionList} from '@primer/react'

const items = [{label: 'Item one'}, {label: 'Item two'}, {label: 'Item three'}]

export default function SingleSelect() {
  const [selectedIndex, setSelectedIndex] = React.useState(0)

  return (
    <ActionList selectionVariant="single" role="menu" aria-label="Item">
      {items.map((item, index) => (
        <ActionList.Item
          key={index}
          role="menuitemradio"
          selected={index === selectedIndex}
          aria-checked={index === selectedIndex}
          onSelect={() => setSelectedIndex(index)}
        >
          {item.label}
        </ActionList.Item>
      ))}
    </ActionList>
  )
}

Multi-select

Selection state guidelines

import React from 'react'
import {ActionList} from '@primer/react'


const items = [{label: 'Item one'}, {label: 'Item two'}, {label: 'Item three'}]


export default function MultiSelect() {
  const [selectedIndices, setSelectedIndices] = React.useState<number[]>([0])
  const handleSelect = (index: number) => {
    if (selectedIndices.includes(index)) {
      setSelectedIndices(selectedIndices.filter(i => i !== index))
    } else {
      setSelectedIndices([...selectedIndices, index])
    }
  }


  return (
    <ActionList selectionVariant="multiple" role="menu" aria-label="Item">
      {items.map((item, index) => (
        <ActionList.Item
          key={index}
          role="menuitemcheckbox"
          selected={selectedIndices.includes(index)}
          aria-checked={selectedIndices.includes(index)}
          onSelect={() => handleSelect(index)}
        >
          {item.label}
        </ActionList.Item>
      ))}
    </ActionList>
  )
}

import React from 'react'
import {ActionList} from '@primer/react'

const items = [{label: 'Item one'}, {label: 'Item two'}, {label: 'Item three'}]

export default function MultiSelect() {
  const [selectedIndices, setSelectedIndices] = React.useState<number[]>([0])
  const handleSelect = (index: number) => {
    if (selectedIndices.includes(index)) {
      setSelectedIndices(selectedIndices.filter(i => i !== index))
    } else {
      setSelectedIndices([...selectedIndices, index])
    }
  }

  return (
    <ActionList selectionVariant="multiple" role="menu" aria-label="Item">
      {items.map((item, index) => (
        <ActionList.Item
          key={index}
          role="menuitemcheckbox"
          selected={selectedIndices.includes(index)}
          aria-checked={selectedIndices.includes(index)}
          onSelect={() => handleSelect(index)}
        >
          {item.label}
        </ActionList.Item>
      ))}
    </ActionList>
  )
}

Grouping items with a heading

Items
Listings

<ActionList>
  <ActionList.Group>
    <ActionList.GroupHeading as="h3">Items</ActionList.GroupHeading>
    <ActionList.Item>Item one</ActionList.Item>
    <ActionList.Item>Item two</ActionList.Item>
    <ActionList.Item>Item three</ActionList.Item>
  </ActionList.Group>
  <ActionList.Group>
    <ActionList.GroupHeading as="h3">Listings</ActionList.GroupHeading>
    <ActionList.Item>Listing one</ActionList.Item>
    <ActionList.Item>Listing two</ActionList.Item>
    <ActionList.Item>Listing three</ActionList.Item>
  </ActionList.Group>
</ActionList>

<ActionList>
  <ActionList.Group>
    <ActionList.GroupHeading as="h3">Items</ActionList.GroupHeading>
    <ActionList.Item>Item one</ActionList.Item>
    <ActionList.Item>Item two</ActionList.Item>
    <ActionList.Item>Item three</ActionList.Item>
  </ActionList.Group>
  <ActionList.Group>
    <ActionList.GroupHeading as="h3">Listings</ActionList.GroupHeading>
    <ActionList.Item>Listing one</ActionList.Item>
    <ActionList.Item>Listing two</ActionList.Item>
    <ActionList.Item>Listing three</ActionList.Item>
  </ActionList.Group>
</ActionList>

Grouping items with a divider

<ActionList>
  <ActionList.Item>Item one</ActionList.Item>
  <ActionList.Item>Item two</ActionList.Item>
  <ActionList.Item>Item three</ActionList.Item>
  <ActionList.Divider />
  <ActionList.Item>Item four</ActionList.Item>
  <ActionList.Item>Item five</ActionList.Item>
  <ActionList.Item>Item six</ActionList.Item>
  <ActionList.Divider />
  <ActionList.Item variant="danger">Delete</ActionList.Item>
</ActionList>

<ActionList>
  <ActionList.Item>Item one</ActionList.Item>
  <ActionList.Item>Item two</ActionList.Item>
  <ActionList.Item>Item three</ActionList.Item>
  <ActionList.Divider />
  <ActionList.Item>Item four</ActionList.Item>
  <ActionList.Item>Item five</ActionList.Item>
  <ActionList.Item>Item six</ActionList.Item>
  <ActionList.Divider />
  <ActionList.Item variant="danger">Delete</ActionList.Item>
</ActionList>

More code examples

The previous examples are a curated subset of the full capabilities of the ActionList component. For more examples, see the ActionList Storybook stories.

Props

ActionList

Name	Required	Description
children	Required	`ActionList.Item[] \| ActionList.LinkItem[] \| ActionList.Group[]`
variant		`'inset' \| 'full'` `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.
showDividers		`boolean` 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`

ActionList.Item

Name	Required	Description
children	Required	`React.ReactNode \| ActionList.LeadingVisual \| ActionList.Description \| ActionList.TrailingVisual` Primary content for an Item
variant		`'default' \| 'danger'` `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. `event.preventDefault()` will prevent a menu from closing when within an `<ActionMenu />`. This is not called for disabled or inactive items.
selected		`boolean` Indicate whether the item is selected. Only applies to items that can be selected.
active		`boolean` Indicate whether the item is active. There should never be more than one active item.
disabled		`boolean` Items that are disabled can not be clicked, selected, or navigated to.
inactiveText		`string` Text describing why the item is inactive. This may be used when an item's usual functionality is unavailable due to a system error such as a database outage. If there is a leading visual, the alert icon will replace the leading visual. If there is a trailing visual, it will replace the trailing visual. If there is no visual passed, it will be shown in the trailing visual slot to preserve left alignment of item content. Text will appear in a tooltip triggered by the alert icon in ActionList items, but text will appear below the description or title on ActionMenu items.
loading		`boolean` Whether the item is loading.
role		`AriaRole` ARIA role describing the function of the item. `option` is a common value.
id		`string` id to attach to the root element of the Item
sx		`SystemStyleObject`

ActionList.Heading

Name	Required	Description
children	Required	`React.ReactNode` Use to give a heading to list
as		`h1 \| h2 \| h3 \| h4 \| h5 \| h6` The level of the heading
visuallyHidden		`boolean`
sx		`SystemStyleObject`

ActionList.LinkItem

Name	Required	Description
children	Required	`React.ReactNode \| ActionList.LeadingVisual \| ActionList.Description \| ActionList.TrailingVisual`
active		`boolean` Indicate whether the item is active. There should never be more than one active item.
ref		`React.RefObject<HTMLAnchorElement>`
as		`React.ElementType`
inactiveText		`string` Text describing why the item is inactive. This may be used when an item's usual functionality is unavailable due to a system error such as a database outage.
sx		`SystemStyleObject`

ActionList.LeadingVisual

Name	Required	Description
children	Required	`React.ReactNode` Icon (or similar) positioned before item text.
sx		`SystemStyleObject`

ActionList.TrailingVisual

Name	Required	Description
children	Required	`React.ReactNode` Visual positioned after item text.
sx		`SystemStyleObject`

ActionList.TrailingAction

Name	Required	Description
as		`a \| button` HTML element to render as.
label	Required	`string` Acccessible name for the control.
icon	Required	`string` Octicon to pass into IconButton. When this is not set, TrailingAction renders as a `Button` instead of an `IconButton`.
href		`string` href when the TrailingAction is rendered as a link.

ActionList.Description

Name	Required	Description
children	Required	`React.ReactNode`
variant		`'inline' \| 'block'` `inline` descriptions are positioned beside primary text. `block` descriptions are positioned below primary text.
sx		`SystemStyleObject`
className		`string \| undefined` CSS string
truncate		`boolean` Whether the inline description should truncate the text on overflow.

ActionList.GroupHeading

Name	Required	Description
children	Required	`React.ReactNode` Use to give a heading to the groups
variant		`'filled' \| 'subtle'` `filled` style has a background color and top and bottom borders. Subtle style has no background or borders.
auxiliaryText		`string` Secondary text which provides additional information about a `Group`.
visuallyHidden		`boolean`
as		`h1 \| h2 \| h3 \| h4 \| h5 \| h6` The level of the heading and it is only required (enforce by runtime warning) for lists. (i.e. not required for ActionMenu or listbox roles)
sx		`SystemStyleObject`

ActionList.Group

Name	Required	Description
children	Required	`ActionList.Item[] \| ActionList.LinkItem[]`
title Deprecated		`string` Please use `ActionList.GroupHeading` instead.
auxiliaryText		`string` Secondary text that provides additional information about the group.
variant		`'filled' \| '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`

ActionList.Divider

Name	Required	Description
sx		`SystemStyleObject`