- Use to logically group items that follow the same content structure.
List Item
A list item is a single element in a list that displays specific information in an organised manner.
Dos and Don'ts
- Do not use if the list content needs to be nested more than one level deep and becomes overly complex and lengthy.
Anatomy
- Primary text: Provides an overview of the content.
- Secondary text (Optional): Provides additional detail if required.
- Divider (Optional): Visually defines the end of one list item and the beginning of the next.
- Icon (Optional): Non-interactive icon that visually supports the primary text.
- Icon with background (Optional): Non-interactive icon that visually supports the primary text.
- Avatar (Optional): Visually supports the primary text if it references an individual or business.
- Payment method icon (Optional): Non-interactive payment method icon that supports the primary text.
- Thumbnail (Optional): Small image or media content that visually supports the primary text.
- Checkbox (Optional): Interactive element that allows users to select or deselect options from a list of choices.
- Radio (Optional): Interactive element that allows users to select a single option from a predefined set of choices.
- Icon - interactive (Optional): Interactive icon that indicates an action.
- Meta text (Optional): Provides more information about the context, status, or attributes of the primary content.
- Tag (Optional): Visual element used to represent and categorise information, only non-interactive variants permitted.
- Switch (Optional): Interactive element that allows users to switch between two states.
Variants
Non-interactive
The non-interactive variation should be used when the list item doesn't require any component level interactive states tied to the instance.
Interactive - Form selection
Includes form elements such as checkbox, radio or switch, which allows the user to make one or multiple choices.
Interactive - Navigation
Functions as a link to redirect the user to a new destination.
Interactive - Action
Functions as a button to trigger an immediate operation or event.
Modifiers
Compact
The height of the component is decreased to reduce the vertical space, and used when space needs to be saved.
Secondary text
The secondary text can be used to provide additional content that supports the primary text.
Bold primary text
There's an option to use bold in the primary text.
Leading content
Non-interactive
Interactive
Trailing content
Non-interactive
Interactive
Divider
The divider is optional. It is used to visually separate individual list items from each other. Dividers should never be used on the last item within a group.
Overrides
Variants
- Avatar: The Avatar's variants can be overridden.
- Tag: The Tag's variants can be overridden.
- Icon with background: The Icon with background's variants can be overridden.
Alignment / Layout
- Alignment: The vertical alignment of both leading and trailing content can be adjusted to centre alignment. However, both must maintain the same alignment.
- Vertical spacing: Vertical padding can be removed when being used within a component e.g. Modal, bottom sheet.
Selected state
Navigation
- Icon colour: The icon colour token can be overridden with
$color-content-brand-solidto provide an additional visual cue. - Tick icon: Highly recommended using the tick icon to indicate the selected page or link. Optional when the distinction between states is clear.
Layout
Groups
List items can be stacked vertically to form a group, and groups can also be paired horizontally.
Form controls
The radio form controls should always be used within a group, allowing users to make a single selection from a predefined set of options.
Sizes
Height
Depending on the properties applied to the component, the minimum height of the component fluctuates.
| Compact | Secondary text | Minimum height | Notes |
|---|---|---|---|
| No | No | 56px | One line of primary text. |
| No | Yes | 76px | One line of primary and secondary text. |
| Yes | No | 48px | One line of primary text. |
Interactions
Interactive
The entire container for interactive variants is clickable.
Overflow
Primary and secondary text
The recommendation is to keep the copy short and concise to allow users to easily browse. If the length of the primary or secondary text exceeds the available horizontal space, the content will wrap onto a new line with no maximum.
Trailing content
If the trailing content contains a text element, its maximum width is 1/3 of the available space. If the width is exceeded the content will wrap onto a new line.
States
Interactive list items have two states: unselected and selected. How the selected state is presented depends on the interaction type.
Form selection
When a form control is present, the form control element indicates the selected state.
Navigation
In navigation, the currently selected item should be indicated using bold text, with an optional tick icon. Apply this convention consistently throughout the experience.
If bold text is used for unselected items, a trailing tick icon should always be present to clearly distinguish them from the selected state. Additionally, the icon can use a brand colour to provide an additional visual cue and reinforce the distinction between states.
Action
Action list items are selectable and users can interact with them, but they do not require a persistent selected state. Selecting an action triggers an immediate outcome rather than indicating which item is currently selected.
No selected state
Interactive states
The interactive variation includes all interactive states, while the non-interactive variation only includes the default state.
Disabled
Navigation type does not support a disabled state.
Examples
LTR examples
Here are some examples of list items in left-to-right context:
RTL examples
Here are some examples of list items in right-to-left context:
