DescriptionList
Label-and-value pairs — the block on every detail page in the platform.
Why it exists
<dl> appears in 18 files across the suite and <dt> 72 times, sixty-one of them carrying the identical text-[var(--muted)]. The values were consistent; the container was not — sixteen different class strings on the <dl> itself, for what is really two layouts.
- Version
- v4
- Ends in
- …9f2c
- Set by
- budi@example.co.id
- Created
- Last rotated
- never
An empty value renders a dash, not nothing
A row that disappears when its value is null makes two records with different fields missing look like two different kinds of record. “—” says we looked; empty says nothing at all. empty takes the word that is actually true — “never” for a rotation that has not happened.
- Last rotated
- never
- Assignee
- Unassigned
- Note
- —
The metadata strip
The other layout: pairs flowing along a line under a heading. It is a separate component rather than a prop because the grid needs its dt and dd as its own cells, and a strip needs them wrapped so a label never wraps away from its value. One component cannot be both.
- Status
- NEEDS APPROVAL
- Started
- Workflow
- nightly-reconcile
- Attempt
- 3 of 5
Stacked, for a summary
Label above value, in a row of columns that wraps. Close to Stat, and the difference is what the value is: Stat is a number you compare over time, this is a fact you read once.
- Region
- ap-southeast-3
- Runtime
- Node 22
- Image
- ivy:4e3e84f
- Tier
- production
In both themes
light
- Version
- v4
- Set by
- budi@example.co.id
dark
- Version
- v4
- Set by
- budi@example.co.id
Guidance
Use it when
- A detail page's facts about one record — the block beside or under the main content.
- layout="inline" for a metadata strip under a heading.
- empty with the word that is true: “never”, “Unassigned”, “Not set”.
Reach for something else when
- The same field across many records. Down a column is Table's job; that is what makes them comparable.
- A term that is a sentence. These are names, and the grid's first column is sized to the longest one.
- Two divs instead. The association is the point — a screen reader announces “Version, v4” as a pair.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| layout | "grid" | "inline" | "stacked" | "grid" | grid: labels in a column. inline: a wrapping strip. stacked: label above value. |
| term | ReactNode | — | The label. A name, not a sentence. |
| empty | ReactNode | "—" | Rendered when the value is null, undefined or empty. |
Accessibility
A real <dl>, and that is the reason to use this rather than a two-column div. A screen reader announces “Version, v4” as a pair; two divs announce “Version” and then, separately, “v4”, and in a block of eight the reader has to hold the alternation in their head to know which is which.