DataList
Key-value pairs rendered as a description list
Category: display · WCAG 2.2-AA · key-value, description, metadata, details
Variants
- horizontal
- vertical
Sizes
- sm
- md
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | DataListEntry[] | — | The label/value pairs to render. Optional: pass `<DataListItem label="…">value</DataListItem>` children instead when a value needs surrounding JSX. |
orientation | 'horizontal' | 'vertical' | horizontal | Where each value sits relative to its own label: 'horizontal' beside it, 'vertical' underneath. Items are stacked vertically in both modes — this does not change the list's own axis. |
dividers | boolean | false | When true, shows dividers between items. |
size | 'sm' | 'md' | md | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
children | ReactNode | — | `<DataListItem>` rows, as an alternative to `items`. |
Design tokens
--cascivo-color-text--cascivo-color-text-subtle--cascivo-color-border--cascivo-space-3--cascivo-space-4
When to use
- Displaying read-only key-value metadata (profile fields, record summaries)
- Presenting structured attributes where each value maps to a single label
- Compact detail panels next to or below a primary subject
When not to use
- Editable fields — use form Inputs, not a DataList
- Tabular data with many rows and columns — use a Table
How to build an accessible DataList in React →
Examples
Horizontal data list
<DataList
items={[
{ label: 'Name', value: 'Ada Lovelace' },
{ label: 'Role', value: 'Mathematician' },
]}
/>Vertical — value under its label, not "items stacked vertically"
Both modes stack the items vertically. `orientation` moves the VALUE: beside its label (horizontal) or under it (vertical).
<DataList
orientation="vertical"
items={[
{ label: 'Region', value: 'fra1' },
{ label: 'Branch', value: 'main' },
]}
/>Vertical with dividers
<DataList
orientation="vertical"
dividers
items={[{ label: 'Email', value: '[email protected]' }]}
/>Related components
- ContainedList — ContainedList shows single-value rows; DataList shows labelled pairs