An iOS-style list. Rows are separated by inset hairline dividers that
begin at the title, and each takes an optional leading tile, a description, a
trailing slot, and an automatic drill-in chevron. contained draws the
rows as a card, and List.Group breaks them into titled sections.
import { List } from '@oztix/roadie-components/list'
A row needs only a title. With no href it renders as a <button>.
Rows sit flush, divided by an inset hairline, and are individually
rounded. The rounding shows as soon as a row picks up a fill on hover or
selection, and the hairlines either side of it turn transparent.
<List> <List.Item title='Account' /> <List.Item title='Notifications' /> <List.Item title='Privacy' /> </List>
emphasis names the surface. Pick subtler (default, no fill), subtle
(tinted), or normal (bordered). It lands on each row, so the rows read
as a run of pills. The values are Roadie's own emphasis shortcuts, not a
List-local palette, so a row's rest, hover and press states come from the
same place as a Button's.
subtler rows sit flush and lean on the inset hairline to separate them;
the hairline turns transparent around any row wearing a fill, so it never
cuts through one. A filled emphasis needs no hairline at all. Those rows
are visible surfaces, so they gap apart instead and drop the dividers.
All of it runs on selectors: :hover, :focus-visible and aria-current.
Hovering or selecting a row in a long list never re-renders anything.
contained draws the rows as a card: the emphasis surface moves from
the rows to the container, and the rows go square and flush inside it. This is the
iOS Settings shape. Reach for it when the rows are one unit rather than a
menu of separate destinations.
List.Group wraps a run of rows with a List.GroupTitle. A list can mix
loose rows and groups in any order. Each group renders its own section,
so the markup stays a valid <ul> either way. When the list is
contained, every group is its own card and the titles sit above them.
Author groups inside a client component. List.Group finds its title by
element reference, which a server component's Flight boundary hides. A
List of plain List.Items stays server-safe.
List.GroupTitle is an <h2> by default. When the list sits under a
page's own <h2>, pass render to set the level that fits the outline.
The title keeps its styles and still labels its section.
A leading IconTile, a title, and an automatic chevron, because each row
links. contained makes it the iOS Settings shape: one
aligned column of rows sharing a single card.
current marks the current row, such as the active option in an
organisation picker. It sets an accent-tinted fill and aria-current.
Pair it with a trailing CheckIcon; a picked row shows no chevron.
current takes true for a plain selection, or one of 'page', 'step'
and 'location' when the row points at the current page, step or place.
A trailing node and the chevron coexist. The trailing value (a
Badge, count, or status) sits to the left of the chevron. This is the iOS
"value › chevron" pattern.
Pass href and the row routes through RoadieLinkProvider. It uses the same
smart-href contract as Card. External and mailto: / tel: hrefs pick
the right element and target / rel defaults automatically. Links get
a chevron by default; suppress it with chevron={false}.
List so
the dividers and aligned column read as a unit. Don't wrap each row in
its own List.contained when the
rows belong together as a settings card; leave it off when they're
separate destinations, where individually rounded rows read better.List.Group is for sections a reader
scans, such as Account, Privacy and Danger zone. A list of three rows doesn't need
one.href gets a drill-in
chevron for free. Force one on an onClick-only row with chevron, or
suppress it with chevron={false}.current is for pickers. Use current for the chosen option in
a single-select list, paired with a trailing check. Reach for
current='page' only when the row really is the page the reader is on.<ul> of <li> rows. Each row is a
<button> or, with href, a link. Keyboard focus and activation
work out of the box.List.Group is an <li> holding its title and a nested
<ul>, so screen readers announce each section as its own list. The
title is an <h2> that labels its section; render sets another level.description is read as the row's description, not part
of its name, so it is announced once.current sets aria-current on the row so screen
readers announce the active choice.Surface for each row, or for the card when `contained`.
Draw the rows as one card; each `List.Group` gets its own.
Defaults to false.
A titled section of rows inside a `List`. Author it in a client component.
`List.GroupTitle` followed by the group's `List.Item`s.
Label for a `List.Group`.
Change the heading level, e.g. `render={<h3 />}`. Defaults to `<h2>`.
A row in a `List`: a link when `href` is set, otherwise a `<button>`.
Primary text; the only required prop.
Secondary line beneath the title.
Leading slot — an `IconTile`, `Image`, or avatar.
Trailing slot — a count, `Badge`, value, or selected check.
Show the drill-in chevron; defaults to whether `href` is set.
Link target, routed like `Card`'s `href`; omit to render a `<button>`.
Marks the item as current; `true` or a token sets `aria-current`.
Defaults to false.