action-list

12 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Action list definition and applications

An action list is a vertical list of interactive actions or options composed of items presented in a consistent, single-column format with room for icons, descriptions, side information, and other rich visuals. Action lists are the foundation of menus, select panels, and nav lists. They can be applied to page sidebars for showing individual actions, handling local navigation, and displaying metadata.

Action list support for device sizes and states

Action lists use a mobile-friendly inset style with sizes adapted on touch devices, and their single-column format should render consistently in any screen size. Items in an action list are generally interactive and respond visually to hover, active, and focus states. Disabled and read-only items are also supported.

Action list composition elements

An action list can be composed of: action list items, item dividers, section headers (subtle or filled styles), and section dividers (subtle or filled styles).

Leading visuals in action list items

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. When listing system sections, features, or options, use leading visuals to improve scannability. In user-generated objects, they can help indicate the item's content type and status. Displaying a leading visual may not be necessary in all contexts, such as in a list of branches in a select panel.

Trailing visual and text in action list items

Trailing visual and trailing text can display auxiliary information at the right of the item and can denote status, keyboard shortcuts, or set expectations about what the action does. These side visuals do not have dedicated interaction targets. Use an arrow-right octicon in menus to indicate the action will open more options, such as in a nested context. Use a pencil octicon to indicate the item will be edited after clicking. Custom trailing elements like counters and labels are supported. When using trailing text for keyboard shortcuts, confirm characters match the user's operating system (for example, Ctrl+B on Linux/Windows and ⌘B on Mac).

Trailing action buttons in action list items

Trailing action buttons can be used to present a secondary interaction related to the contents of the main item, such as opening a menu or dialog. They may appear when an item is hovered and can be keyboard focused individually.

Item dividers in action lists

Item dividers are placed between items and allow users to parse heavier amounts of information. They are useful in complex lists, particularly when descriptions or multi-line text is present. Item dividers should only be used if they truly make the presented information easier to parse rather than only increasing visual clutter. When using item dividers, increasing the action list item size may also help with legibility.

Selection states in action lists

Action list items support single select and multi-select. Selections are represented with a check octicon placed at the beginning of the item. When listing selectable items alongside non-selectable items in a menu, use dividers to differentiate between the item types. Do not mix single select and multi-select in the same list.

Danger items in action lists

An action list item can have a special danger style to be used in cases that require extra attention from the user. For destructive or irremediable actions, show a confirmation dialog for extra friction. If the action is not destructive, present the user a way to undo the action instead of asking for confirmation. Place danger items at the end of the list.

Inactive items in action lists

Inactive action list item text still needs to meet an accessible color contrast ratio. It is required to show a tooltip with context about why the item is inactive, triggered by the alert icon in the leading visual or trailing visual. If there is a leading visual, replace it with an alert icon. If there is not a leading visual, the alert icon is put in the same position as the trailing visual.

Loading items in action lists

If an action list item is not yet interactive because the required data is still loading, it may be rendered in a loading state. The position of the loading icon depends on the same logic as where the alert icon goes in inactive items: if there is a leading visual, replace it with a loading indicator; if there is not a leading visual, the loading indicator is put in the same position as the trailing visual.

Action list component identification

The action list component has the React ID 'action_list', Rails ID 'Primer::Alpha::ActionList', and Figma ID 'action_list'.

Give your agent this brain