List

Settings-style list with grouped sections, separators and press feedback. Rows can brighten under your finger and appear one after another in reading order.

Preview

Installation

npx @lumioui/cli add list

Usage

import { List } from "@/components/ui/list/list";
<List />

Examples

Contacts

A share-sheet recipient picker on a lit list: rows switch on 40ms apart and brighten under the finger.

Glass

Playback settings on a glass section over the album art they belong to; the only place glass earns its keep is over content.

Orders

An order history screen: an in-transit group above past orders, store marks in colour, totals right-aligned in tabular figures.

API reference

List

Prop Type Default
inset boolean

Inset-grouped style: rounded card sections with horizontal margin.

—
glass boolean

Glass section material (pairs naturally with inset).

—
lit boolean

Lit press: a held row brightens (foreground light on dark, accent light on light) instead of taking the muted ink wash. Default false.

—
switchOn boolean

Switch on at mount: each section's rows start dim and switch on 40ms apart, sections one band (120ms) apart. Default false.

—
className string —

ListSection

Prop Type Default
title string

Optional header text rendered above the group.

—
titleClassName string

Extra classes for the header text.

—
footer string

Optional footnote under the group — a short explainer line.

—
className string —

ListItem

Prop Type Default
title* string

Primary label.

—
subtitle string

Secondary label under the title.

—
leading React.ReactNode

Slot rendered before the text block (icon, avatar, etc.).

—
trailing React.ReactNode

Slot rendered after the text block, before the chevron.

—
showChevron boolean

Show a disclosure chevron on the trailing edge.

—
haptic
"light" | "medium" | "heavy" +2 "light" | "medium" | "heavy" | "selection" | false

Haptic on press. Default "selection"; false to disable.

—
className string —
titleClassName string —
subtitleClassName string —
density "default" | "compact"

Vertical rhythm: "default" for standard rows, "compact" for dense rails (media pickers, followers) where more rows must fit the fold.

—
titleNumberOfLines number

Title line clamp. Default 1 — event/news rows that must not lose their tail should pass 2.

—
subtitleNumberOfLines number

Subtitle line clamp. Default 2.

—
children React.ReactNode —

ListSeparator

Prop Type Default
inset boolean | "none" | "icon" | "text" | number

Left inset preset: - omitted (default): 16px — under the text start of a row without a leading slot (hairlines never run full-bleed inside a section). - "none"/false: full-bleed. - "icon"/true: starts under the leading slot edge (16px — the row's px-4). Legacy inset maps here for pixel parity. - "text": aligns under the title text, past a standard 24px leading icon (16px padding + 24px icon + 12px gap = 52px). - number: exact px inset — match your leading slot's width.

—
className string —