List
The Simple List component is used to display a group of related items in a list format. It’s integrated into other components such as dropdowns, side panels, or cards, wherever there’s a need to present structured information or a set of options.
Its purpose is to offer a clear, scannable representation of items, ensuring they are easily navigable both visually and via keyboard or screen readers.
When to use it (and when not to)
Section titled “When to use it (and when not to)”Use the Simple List when you need to:
- Display groups of related items, such as options or categories.
- Present content that doesn’t require complex interaction beyond item selection or viewing.
- Integrate a list inside other container components like dropdowns (e.g. lists of options) or modals and side panels (lists of actions or links).
Do not use this component for tabular or multi-column data — in those cases, use a Data Table or similar component.
Quick summary of accessibility & consistency
Section titled “Quick summary of accessibility & consistency”Follow accessibility best practices to ensure the Simple List is usable for everyone. Use native HTML elements whenever possible, maintain proper focus order, and provide clear visual feedback for interactive states. Make sure text and icons meet minimum contrast ratios, and that all actions can be performed using a keyboard alone. If the list’s purpose isn’t obvious from context, provide an accessible name or label to help screen reader users understand its content and function.
Properties
Section titled “Properties”Simple List
Multiselect
Layout and spacing
Section titled “Layout and spacing”Type : Simple List
Section titled “Type : Simple List”List
Simple List
Type : Multiselect
Section titled “Type : Multiselect”List
Frame (Checkbox List + CTA)
Styling
Section titled “Styling”Colors
Section titled “Colors”| Name | Applied as | Applied to |
|---|---|---|
color-foreground-neutral-default | Text color | List option label |
color-foreground-neutral-default | Text color | List option label |
color-foreground-neutral-subtle | Text color | List option (hover) |
color-foreground-neutral-subtle | Text color | List option (hover) |
color-foreground-contrast-default | Text color | List option link (contrast) |
color-foreground-contrast-default | Text color | List option link (contrast) |
color-surface-neutral-subtle | Background color | List option (hover / selected) |
color-surface-neutral-subtle | Background color | List option (hover / selected) |
color-border-contrast-default | Border color | Divider line |
color-border-contrast-default | Border color | Divider line |
color-border-neutral-default | Border color | Divider line (hover) |
color-border-neutral-default | Border color | Divider line (hover) |
color-border-focus-neutral-default | Border color | List option (focus) |
color-border-focus-neutral-default | Border color | List option (focus) |
Spacing
Section titled “Spacing”| Name | Applied as | Applied to |
|---|---|---|
spacing-04 | Gap / Padding block | List option |
spacing-04 | Gap / Padding block | List option |
spacing-08 | Padding block / Padding inline / Gap | List option (no image) |
spacing-08 | Padding block / Padding inline / Gap | List option (no image) |
spacing-10 | Padding inline | Checkbox control |
spacing-10 | Padding inline | Checkbox control |
Accessibility
Section titled “Accessibility”For Design
Section titled “For Design”All list items and states (rested, hover, selected and focus) must maintain accessible contrast.
Focus styles must remain visible and meet WCAG AA contrast requirements across all supported surfaces. Focus should be clearly distinguishable from hover.
Colour tokens used should be semantic (e.g. foreground/neutral/default) rather than fixed values. This ensures the component adapts correctly to different themes or surfaces.
For Dev
Section titled “For Dev”To ensure the list meets WCAG 2.1 AA and supports assistive technologies, follow these implementation standards:
-
Semantic HTML — Use native HTML elements:
<ul>for unordered lists,<ol>for ordered lists or hierarchical data. Each item should be inside an<li>. If the list is interactive (e.g. items can be clicked or selected), each<li>may contain a<button>or<a>, depending on its behavior: use<button>when the action happens in the same context, use<a>when it navigates to another page or view. -
Keyboard Navigation — If items are non-interactive, navigation is handled naturally by the screen reader’s virtual cursor. If items are interactive (buttons, links, etc.), they must be focusable (
tabindex="0"or native focusable elements like<button>or<a>). The focus state should be visually clear. Focus order must follow the logical DOM order. -
Focus Ring / Visible Focus — List items must display a visible focus style, not only a colour change.
-
Screen Reader Support — Ensure the list has an accessible name when the context isn’t obvious (using
aria-labeloraria-labelledby). Screen readers will automatically announce the number and position of items (“list with 5 items”, “item 1 of 5”, etc.) when using native list markup. -
Responsive and Tap Targets — Interactive area must be at least 44 px in height to support touch accessibility.
-
Roles and ARIA attributes — In most cases, no additional ARIA roles are needed since the native semantics of
<ul>/<li>are sufficient. Only if the list has a more complex interactive behavior (e.g. a selectable list or “listbox”), the following may apply:role="listbox"on the container,role="option"on each item,aria-selected="true"to indicate the selected item.
- Keep list item labels concise. Aim for short, scannable text that fits naturally on one line.
- Ensure each item contains only one line of text. The component is designed for single-line labels to maintain clarity and visual consistency.
- Use clear and meaningful wording. Each label should communicate its purpose without extra detail or filler.
- Review long labels individually. If an item requires more characters, evaluate it in isolation to determine whether truncation is appropriate for that specific case.
- Use the List only for simple, straightforward options. It should present clear choices without additional descriptions or metadata.
- Don’t include two lines of text. Multi-line labels break the component layout and the intended interaction patterns.
- Don’t truncate by default. Truncation should be an exception, not the rule. Avoid shortening content unless absolutely necessary and approved case by case.
- Don’t overload items with extra information. Only use sublabels, icons, tags, or any secondary text when needed.
- Don’t rely on the List to communicate complex messages. If the content is too long or detailed, consider a different component or content strategy.
- Don’t use inconsistent wording lengths. Excessively long items next to very short ones create visual imbalance — keep content harmonised.
Usage Guidelines
Section titled “Usage Guidelines”Use the List component to display a set of simple, scannable options — typically within other components such as dropdowns, menus, or selection patterns. Each item should present a clear, single-line label that helps users quickly read and compare choices.
Keep the content concise to avoid layout issues and ensure a smooth browsing experience. If an item requires more text than usual, review it individually to determine whether truncation is appropriate or whether the content should be rephrased or moved to a different component.
Lists work best when presenting straightforward choices without additional metadata or complexity.