Anatomy
The List consists of two primary elements that work together to present content in a structured format.- List container – The wrapper that renders as either an unordered list (
ul) or ordered list (ol), applying typography and spacing from the design system. - List item – Individual items within the list, rendered as
lielements.
Options
The List supports the following configurations to accommodate various content and layout scenarios.Variant
Lists can be unordered (bullets) or ordered (numbers). Use unordered lists for items without sequence; use ordered lists for steps, rankings, or sequence-dependent content.| Variant | Use case |
|---|---|
| Unordered | Bullet points, non-sequential items |
| Ordered | Steps, rankings, numbered items |
Size
Typography size aligns with the design system paragraph scale. Size affects readability and hierarchy when lists appear alongside other content.| Size | Description |
|---|---|
| Small | Compact content or dense UIs |
| Medium | Default body size |
| Large | Emphasis or larger text blocks |
Nesting
Lists support nesting. Place a List inside a List item to create sub-lists (for example, an ordered sub-list inside an unordered parent).Behavior
The List responds to the chosen variant and size without interactive states. It renders semantic HTML so screen readers announce list structure and item count correctly.Usage Guidelines
Use the List when presenting content as a series of items that benefit from list semantics and design system styling.When to Use
- Displaying bullet points or numbered steps in body content.
- Outlining options, features, or requirements.
- Showing sequential instructions or ordered criteria.
- Grouping related items with clear visual hierarchy.
When not to use
- Selectable options – Use Listbox or Menu for user selection.
- Data grids or tables – Use ListView or Data Table for tabular or multi-column data.
How to Use
UseList with List.Item for each entry. Set variant="ordered" for numbered lists; omit it or set variant="unordered" for bullet lists.
Do
Don’t