Skip to content

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
  • github.com/primer
  • mona
  • 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.

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
falseDisplay 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

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.
selected
boolean
falseIndicate whether the item is selected. Only applies to items that can be selected.
active
boolean
falseIndicate whether the item is active. There should never be more than one active item.
disabled
boolean
falseItems 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

NameTypeDefaultDescription
children Required
React.ReactNode | ActionList.LeadingVisual | ActionList.Description | ActionList.TrailingVisual
active
boolean
falseIndicate 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

NameTypeDefaultDescription
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

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

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
Style overrides to apply to the component. See also overriding styles.

ActionList.Group

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

Further reading

Edit this page on GitHub
5 contributorscolebemissiddharthkpjfuchssmockleVanAnderson
Last edited by colebemis on May 16, 2022