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
HTML
<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.

HTML
<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 ul or ol and li where appropriate. Put item labels and supporting details in a meaningful reading order.
  • Use links for destinations and buttons for commands. .list-item-action does 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.

TokenDefaultPurposeScope / state
--list-paddingvar(--spacer-0)Inner spacing..list
--list-border-widthvar(--border-width)Border thickness..list
--list-border-colorvar(--border-color)Border color..list
--list-border-radiusvar(--border-radius)Corner radius..list
--list-item-bg-colorvar(--bg-surface)Row background..list
--list-item-padding-yvar(--spacer-2)Row top and bottom padding..list
--list-item-padding-xvar(--spacer-3)Row left and right padding..list
--list-item-gapvar(--spacer-2)Space between row contents..list
--list-item-active-colorvar(--action-color)Text color of the active row..list
--list-item-hover-colorvar(--action-color)Text color of an action row on hover..list
--list-item-transition-durationvar(--transition-duration)Duration of row state transitions..list
--list-item-transition-easingvar(--transition-easing)Timing curve of row state transitions..list