List
Related passive or interactive items.
When to use
Use a list for related rows of content, metadata or actions. Choose native list elements when the items form a collection, and use a Table for data that needs row-and-column relationships.
Default
Use .list-item-text for one or two lines, with optional icons.
- Project overview
- Launch checklist3 tasks remaining
<ul class="list">
<li class="list-item"><span class="list-item-text">Project overview</span></li>
<li class="list-item">
<span class="icon"><!-- Icon --></span>
<span class="list-item-text">
<span>Launch checklist</span>
<small class="text-muted">3 tasks remaining</small>
</span>
</li>
</ul>Interactive
Use native links or buttons. Mark the current destination with .is-active and aria-current.
<nav class="list" aria-label="Example navigation">
<a class="list-item is-active" href="/current" aria-current="page">
<span class="list-item-text">Overview</span>
</a>
<a class="list-item" href="/next">
<span class="list-item-text">Activity</span>
</a>
</nav>Accessibility and behavior
- Preserve list semantics with
ulorolandliwhere appropriate. Put item labels and supporting details in a meaningful reading order. - Use links for destinations and buttons for commands.
.list-item-actiondoes not turn a generic wrapper into an accessible control. - Keep disabled state on native buttons and preserve visible focus styles. Express status in text as well as badges or colors.
CSS variables
Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.
| Token | Default | Purpose | Scope / state |
|---|---|---|---|
--list-padding | var(--spacer-0) | Inner spacing. | .list |
--list-border-width | var(--border-width) | Border thickness. | .list |
--list-border-color | var(--border-color) | Border color. | .list |
--list-border-radius | var(--border-radius) | Corner radius. | .list |
--list-item-bg-color | var(--bg-surface) | Row background. | .list |
--list-item-padding-y | var(--spacer-2) | Row top and bottom padding. | .list |
--list-item-padding-x | var(--spacer-3) | Row left and right padding. | .list |
--list-item-gap | var(--spacer-2) | Space between row contents. | .list |
--list-item-active-color | var(--action-color) | Text color of the active row. | .list |
--list-item-hover-color | var(--action-color) | Text color of an action row on hover. | .list |
--list-item-transition-duration | var(--transition-duration) | Duration of row state transitions. | .list |
--list-item-transition-easing | var(--transition-easing) | Timing curve of row state transitions. | .list |