Keep row anatomy consistent so users can scan quickly.
List
Vertical rows for navigation or actions, with optional leading and trailing slots.
-
.source-list
Container (
ulorol) -
.source-list-item
Row wrapper (
li) -
.source-list-item-inner
Interactive shell (
a,button, ordiv) - .source-list-item-leading Leading icon slot
- .source-list-item-body Text block (label + optional description)
- .source-list-item-trailing Trailing meta/action slot
States
- Default Normal resting state
-
Disabled Not interactive, reduced opacity
StateBehavior
DefaultTransparent background, primary label text, secondary description text.
HoverSurface-raised background fills the inner row.
Focus2px inset outline. Keyboard only.
Disabled
data-source-state="disabled" or aria-disabled="true". Pointer events off, 55% opacity.Design intent
List structures a set of similar items. The most important decision is the row behavior model: link rows navigate, button rows trigger actions, static rows display information. Keep the model consistent within a single list. Mixing types works only when the layout context makes each row's purpose obvious.
Behavior model
href makes the row a link. onClick makes it a button. With neither prop, the row is static content.
Keep each list to one behavior model when possible.
Icon sizing
Use 16px row icons by default. For compact lists, 14px is acceptable. Avoid 12px icons in clickable rows.
Do and don't
Do
Make the row action obvious and keep secondary actions subtle.
Show active or selected rows with more than color only.
Don't
Do not mix links, toggles, and destructive actions without clear grouping.
Avoid multi-line clutter that breaks row rhythm and tap targets.
Do not ship list rows below a usable touch height on mobile.
Designer checklist
- Row behavior is consistent within a list. Do not mix link and button rows without a clear reason.
- Leading icons are either purely decorative or have an accessible text equivalent.
- Selected or active rows are identifiable without relying only on color.
- Clickable rows have a minimum 44px touch target height on mobile.
List props
PropTypeDefaultDescription
variantplain | bordered | dividedplainList visual style.
asul | olulUnderlying list element.
ListItem props
PropTypeDefaultDescription
labelReactNoderequiredPrimary row content.
descriptionReactNodenullSecondary row text.
href / onClickstring / handlernullInteractive mode.
leadingIcon / trailingReactNodenullVisual slots.
Basic usage
import { List, ListItem } from '@pierredelattre/source-react';
<List variant="divided">
<ListItem label="Design tokens" description="Color, spacing, type" href="/foundations" />
<ListItem label="React components" description="Typed UI primitives" href="/components" />
</List>Keyboard support
KeyBehavior
TabMoves through interactive rows.
Enter / SpaceActivates row link/button.