DescriptionList

Semantic list of key/value pairs (<dl>/<dt>/<dd>) under an optional title. It is the design system's primitive for the "label: value" blocks — balances, order summaries, transaction details — that every client used to reimplement by hand.

Both the key and the value accept ReactNode, so a value can be highlighted, become a link or carry an icon without leaving the component.

When to use

✅ Use when…	🚫 Avoid when…
To display a set of related label/value pairs (account summary, deposit details, receipt). When the "term → description" semantics matter for accessibility and for screen readers.	For tabular data with multiple comparable columns/rows. Use `Table` or `DataTable`. For a single isolated value without a label — use `Text`. For editable content (forms) — use `Field`.

Basic usage

Account summary

Available balance: R$ 1.250,00
In orders: R$ 300,00
Total: R$ 1.550,00

import { DescriptionList } from '@apollion-dsi/core/data-display/description-list';
 
const Example = () => (
  <DescriptionList
    title="Account summary"
    contents={[
      { key: 'Available balance', value: 'R$ 1.250,00' },
      { key: 'In orders', value: 'R$ 300,00' },
      { key: 'Total', value: 'R$ 1.550,00' },
    ]}
  />
);

Stacked (`direction="column"`)

For long values (wallet addresses, hashes), stack the value below the key:

Deposit details

Network: Bitcoin (BTC)
Address: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq

<DescriptionList
  direction="column"
  contents={[
    { key: 'Network', value: 'Bitcoin (BTC)' },
    { key: 'Address', value: 'bc1qar0...zwf5mdq' },
  ]}
/>

Dividers (`dividers`)

Rows separated by a thin bottom border — on all but the last (divider semantics, not frame semantics). itemProps remains uniform and can override any border prop:

Tactical facts

Formation: 4-2-3-1
Avg. possession: 58%
PPDA: 9,4

<DescriptionList
  dividers
  contents={[
    { key: 'Formation', value: '4-2-3-1' },
    { key: 'Avg. possession', value: '58%' },
    { key: 'PPDA', value: '9,4' },
  ]}
/>

Value as `ReactNode`

The key and the value accept any ReactNode — highlight a total, add a status badge or a link:

<DescriptionList
  title="Order #1234"
  contents={[
    { key: 'Subtotal', value: 'R$ 100,00' },
    { key: 'Total', value: <strong>R$ 112,00</strong> },
  ]}
/>

Pair gap

The host gap is the space between each key and its value (dt ↔ dd). The title ↔ list shell and the row ↔ row rhythm keep their own fixed spacing, so one prop does not move three things. itemProps.gap still overrides per row.

<DescriptionList direction="column" gap="micro" contents={rows} />

Properties


Prop	Type	Default	Description
`color`	`string`	—	Theme token (`theme.colors`) used as `color`. Has lower precedence than `contrast`: when both are provided, the contrast calculation wins. Stays `string` (not the typed union): `color` is also an HTML attribute (`<li color>`, etc.) and interfaces extending native props require identical types on the name collision.
`containment`	`string`	—	Containment marker for the `cq` channel: emits `container-type` (+ `container-name` when the string form carries one, e.g. `'inline-size card'`). Apply on the immediate wrapper of the adapting component — NEVER on page-level shells.
`contents *`	`DescriptionListItem[]`	—	Key/value pairs displayed in the list.
`direction`	`"row" \| "column"`	`row`	Orientation of each pair.
`dividers`	`boolean`	`false`	Dividers between rows: applies a thin `borderPosition="bottom"` to every row except the last (divider semantics, not a frame). `itemProps` remains uniform and can override any border prop.
`itemProps`	`DescriptionListItemProps`	—	Extra `Flex` props applied to each row (key/value pair).
`legibility`	`"on-photo"`	—	Reading-shadow preset for text over a photographic background (`on-photo`). Replaces the inline `style={{ textShadow }}` in the consumer (brasil_2030 radar, gap A3). Token emission is deferred until a 2nd consumer asks for the raw var (see backlog).
`pageShell`	`boolean`	—	Centers the element and caps the width at `theme.layout.pageMaxWidth`. The page shell of a classic centered layout.
`readable`	`number \| boolean`	—	Makes the `color` legible against the page surface: `true` = WCAG AA (4.5), a number sets a custom floor. Ignored with `contrast`. See the Layout Props concept page for the full semantics.
`title`	`ReactNode`	—	Optional title rendered above the list.
`transform`	`string`	—	CSS `transform` value (e.g. `translate(-50%, -33px)`). Never leaks to the DOM as an attribute.

Beyond the props above, every component accepts the layout props (spacing, color, flex/grid, sizing, border) — not repeated here.

DescriptionList

When to use

Basic usage

Stacked (direction="column")

Dividers (dividers)

Value as ReactNode

Pair gap

Properties

See also

Stacked (`direction="column"`)

Dividers (`dividers`)

Value as `ReactNode`