Skip to content
Primer Design System/React

Primer Design System

Site navigation

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
  • Not reviewed for accessibility
On this page
This documentation is moving to a new home. Please update any link or bookmark that points to this page. The new content can be found here.
  • github.com/primerA React implementation of GitHub's Primer Design System
  • mona
    Monalisa Octocat
  • 4 vulnerabilities
import {ActionList} from '@primer/react'

Examples

Minimal example

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.

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.

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.

With links

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

With groups

Props

ActionList

NameTypeDefaultDescription
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

ActionList.Item

NameTypeDefaultDescription
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. event.preventDefault() will prevent a menu from closing when within an <ActionMenu />. This is not called for disabled or inactive items.

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.

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.

role
AriaRole

ARIA role describing the function of the item. option is a common value.

sx
SystemStyleObject

ActionList.Heading

NameTypeDefaultDescription
children Required
React.ReactNode

Use to give a heading to list

as
React.ElementType
h3

The level of the heading

sx
SystemStyleObject

ActionList.LinkItem

NameTypeDefaultDescription
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.

ref
React.RefObject<HTMLAnchorElement>
as
React.ElementType
"a"

The underlying element to render — either a HTML element name or a React component.

sx
SystemStyleObject
Additional props are passed to the <a> element. See a docs for a list of props accepted by the <a> element.

ActionList.LeadingVisual

NameTypeDefaultDescription
children Required
React.ReactNode

Icon (or similar) positioned before item text.

sx
SystemStyleObject

ActionList.TrailingVisual

NameTypeDefaultDescription
children Required
React.ReactNode

Visual positioned after item text.

sx
SystemStyleObject

ActionList.TrailingAction

NameTypeDefaultDescription
as
React.ElementType
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

NameTypeDefaultDescription
children Required
React.ReactNode
variant
'inline' | 'block'
'inline'

inline descriptions are positioned beside primary text. block descriptions are positioned below primary text.

sx
SystemStyleObject

ActionList.GroupHeading

NameTypeDefaultDescription
children Required
React.ReactNode

Use to give a heading to the groups

variant
'filled' | 'subtle'
'subtle'

filled style has a background color and top and bottom borders. Subtle style has no background or borders.

as
React.ElementType
h3

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

NameTypeDefaultDescription
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'
'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

Status

Alpha

  • Component props and basic example usage of the component 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 robust unit test coverage (100% where achievable).
  • Component has visual regression coverage of its default and interactive states.
  • Component does not introduce any axe violations.
  • Component has been manually reviewed by the accessibility team and any resulting issues have been addressed.

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 does not introduce any performance regressions.

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.
  • Tooling (such as linters, codemods, etc.) exists to prevent further use of alternatives.

Further reading

Related components