Description List
Facts about one thing, as terms and their values: a record's details, a profile, an invoice's totals, a settings overview. The read-only side of a form: it lines up the same way, so a page can switch between showing and editing without moving. To compare many records, use a Table. Specification: docs/components/description-list.md
Basics
A <dl class="canon-description-list"> with a <div> per item: its term (<dt>) and its value (<dd>). Terms sit above their values; lines run between items.
- Invoice
- INV-2041
- Customer
- Edwin Mueller
- Amount
- $495.90
- Due
Terms beside their values
data-label="start", the hint a form uses for its labels: terms in a column a third wide, beside their values, while the list has 32rem; narrower, they go back above. On a page with a form beside the list, set it on their container and both line up. Drag the frame's corner to try it.
- Display name
- Ada Lovelace
- ada@example.com
- Role
- Designer
- Bio
- Writes the first programs for engines that don't exist yet, and the notes that explain them, which run three times as long as the paper they are about.
Columns
data-columns="2" or "3": items side by side, as many columns as fit at 16rem each, up to that number.
- Plan
- Pro
- Seats
- 12 of 15
- Renews
- Billing
- Monthly
- Payment
- Visa ending 4242
- Region
- Europe
Icons as terms
A term can be an icon (aria-hidden="true") with its words visually hidden (canon-visually-hidden): the icon sits beside the value, and screen readers still hear "Date, 10 October 2026". For a panel where the icons say enough at a glance (an event, a contact card); data-lines="none" drops the lines.
- Date
- Category
- Meetings
- Organizer
- ada@example.com
- Notes
- Bring the latest numbers. We'll pick the three projects for the next quarter and who leads each.
Values
A value can hold anything inline: a Tag, a Link, a time, a code with a copy button. A term with several values gets a <dd> for each. An empty <dd> shows a dash that screen readers hear as "Not set" (the --canon-text-not-set string).
- Status
- Paid
- Receipt
- Download PDF
- Participants
- Ada Lovelace
- Grace Hopper
- Katherine Johnson
- Reference
Row actions
A Button or Link after the values sits at the item's end, level with it: "Change" on a settings overview. Name it for its item ("Change email") where several are alike.
- ada@example.com
- Password
- Changed 3 months ago
- Two-factor
- Off
Size
data-size on the list or a container: Table's type and row heights.
- Plan
- Pro
- Seats
- 12 of 15
- Plan
- Pro
- Seats
- 12 of 15
- Plan
- Pro
- Seats
- 12 of 15
Edge cases
Long values wrap, also unbroken ones (a link, an id). Right to left, terms are on the right.
- API key
- sk_live_51HxQ2bKz9vPqR7mN4tY8wE3cL6dF0gH2jK5
- Callback address for payment notifications
- https://example.com/hooks/payments/notify
- الاسم
- آدا لوفلايس
- البريد
- ada@example.com
- المرجع