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.
On this page
On this page
- github.com/primerA React implementation of GitHub's Primer Design System
monaMonalisa 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
| 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. `event.preventDefault()` will prevent a menu from closing when within an `<ActionMenu />` | |
| 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. |
| 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. | |
| as | React.ElementType | "a" | The underlying element to render — either a HTML element name or a React component. |
| sx | SystemStyleObject | Style overrides to apply to the component. See also overriding styles. | |
Additional props are passed to the <a> element. See a docs for a list of props accepted by the <a> element. | |||
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 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.