Description
Pre-requisite for #1069 and #1070
Description
An action list is a simple list of interactive actions or options. It displays a single column of content, divided into items.
Action lists are used in action menus, navigation menus, selection options, and other overlays. They can also be used directly in the page for showing individual actions, for handling local navigation, and for showing metadata.
Action lists can group items into sections, and can use dividers and headers to organize the content.
The ActionList component & its subcomponents are meant to be used mostly internally to build other composite components.
Resources
Figma:
Prototype:
Screenshot
Components
ActionList
Description
Main container for items inside of an ActionList
Screenshot
Props
name: style (default: inset)
type: inset | default
description: sets whether or not to visually inset the list (to allow for a selection checkmark)
name: dividers
type: boolean
description: Adds dividers between all list items. Automatically skips section headers and section dividers.
name: role
type: list | menu | listbox | combobox | radiogroup | tree
description: this is actually just a HTML attribute but we need to make sure it's possible to pass this down to appropriate element in ActionList (probably the outer wrapping element).
ActionList.Item
Description
An action list item is a generic interactive element, which includes a main text and optional icons, descriptions, auxiliary information, and more.
Screenshot
Props
name: type (note: this might make sense to use with variant)
type: default | singleSelection | multiSelection | danger | static
description: Defines the list item type.
name: size
type: small | medium | large
description: Defines how tall the list item is. In an item with a single line, small's height is 32px, medium is 40px, and large 48px. On touch devices, all list items are rendered as large.
name: size
type: small | medium | large
description: Defines how tall the list item is. In an item with a single line, small's height is 32px, medium is 40px, and large 48px. On touch devices, all list items are rendered as large.
Defines how tall the list item is. In an item with a single line, small's height is 32px, medium is 40px, and large 48px. On touch devices, all list items are rendered as large.
For action list items in overlays: Use small for general items with single-line text. You may consider larger sizes if the item is surrounded by other large presentational elements. You can also take advantage of medium and large sizes when additional content is present, such as block description and auxiliary text.
For action list items in a navigation menu: use medium by default. Nested items use small and text-small font size.
name: leadingVisual
type: React.ReactElement or a function that returns multiple elements maybe? Not sure about this.
description: An optional visual to accompany the list item. It supports octicons, avatars, or other custom elements.
name: leadingVisualSize
type: 16 | 20
description: How much space is reserved for the leading visual.
Octicons usually take 16px of area.
Avatars usually take 20px of area.
To center-align a list with 20px avatars and 16px octicons together, place the octicons in a 20px area.
name: text
type: string
description: The primary text in the list item. For actions, use sentence case.
Note: this might be better to pass in as children than as a prop?
name: description
type: string
description: A quick description of the list item.
Note: this might be better to pass in as children than as a prop?
name: descriptionType
type: "inline" | "block"
description: Defines how the description text will be placed in the list item. An inline description appears adjacent to the text prop, while block places it below in a new line.
Note: I'm not sure this is necessary if we decide to pass in text and description through children
name: auxiliaryText
type: string
description: An optional space for auxiliary text at the end of the list item. May be used to render keyboard shortcuts.
When rendering keyboard shortcuts, use the system default characters. On macOS, a keyboard shortcut may look like ⌘S. On Windows, Ctrl+S.
macOS: ⌘ ⌥ ⇧ ⌃
Windows: Ctrl, Shift, Alt
name: auxiliaryIcon
type: Icon
description: An optional space for an auxiliary icon at the end of the list item.
name: disabled
type: boolean
description:
name: selected
type: boolean
description:
name: divider
type: ` "auto" | "forceTrue" | "forceFalse"
description: Whether to show a divider above the item. It replaces the selection from actionList.
name: dividerInset
type: auto | 20px | 24px | 48px | 52px
description: The exact inset spacing the divider should use. auto makes the decision based on the existence of leadingVisual and selection options.
name: nestedContent
type: ???
description: ???
Needs more info cc @vdepizzol
Accessibility considerations
name: role
type: link | listitem | menuitem | menuitemcheckbox | menuitemradio | button | option
aria-level
aria-posinset
aria-setSize
aria-checked
Needs more info
ActionList.Section
Description
An action list section uses the ARIA role property to group elements from a list. Depending on the provided values, it renders a divider, a header, or both.
Screenshot
Props
ActionList.SectionDivider
Description
An action list section divider.
Props
name: style
type: "subtle" | "filled"
default: "subtle"
description: determines the style of the divider
ActionList.SectionHeader
Description
An action list section header.
Props
name: style
type: "subtle" | "filled"
description: determines the style of the header. subtle has no background, filled has a grey background
name: title
type: string (Should we allow folks to pass in a ReactElement here if they want to add non-text content?)
description: text for header content
name: auxiliaryText
type: string (Should we allow folks to pass in a ReactElement here if they want to add non-text content?)