Skip to content

Description List

Term and value pairs for detail pages, settings summaries and record sidebars. A semantic dl with a side-by-side layout that stacks on small screens, or a stacked layout, plus optional dividers and two sizes. Works in server components.

Source

Installation

pnpm dlx shadcn@latest add @desyne/description-list

The CLI installs dependencies and any other components this one uses.

Usage

tsx
import {
  DescriptionDetails,
  DescriptionList,
  DescriptionTerm,
} from "@/components/ui/description-list";
tsx
<DescriptionList divided>
  <DescriptionTerm>Customer</DescriptionTerm>
  <DescriptionDetails>Harbor & Pine Studio</DescriptionDetails>
  <DescriptionTerm>Amount</DescriptionTerm>
  <DescriptionDetails>$4,280.00</DescriptionDetails>
</DescriptionList>

Terms and details are direct children

The layout is a CSS grid on the <dl> that styles its direct <dt> and <dd> children, so put them straight inside DescriptionList, one DescriptionDetails per term. Use a Fragment (not a <div>) when mapping over pairs.

When to use

  • Description List: read-only fields of one record, such as an invoice, a deployment or a user profile.
  • Table: many records that share the same fields.
  • Item: a list of entities with media and actions.
  • Card: a container for a description list with a title.

Anatomy

tsx
<DescriptionList>          {/* <dl>, layout, divided, size */}
  <DescriptionTerm />      {/* <dt> */}
  <DescriptionDetails />   {/* <dd> */}
</DescriptionList>
PartRendersNotes
DescriptionList<dl>Grid. horizontal: term column (minmax(7rem, 33%)) and details column from sm up, stacked below. stacked: one column.
DescriptionTerm<dt>Muted label.
DescriptionDetails<dd>Foreground value. Long words wrap anywhere instead of overflowing.

Examples

Stacked

layout="stacked" puts each term above its details, for narrow sidebars and multi-line values like addresses.

With actions

Details are plain elements, so they can hold badges, links and buttons. Make DescriptionDetails a flex row to push an action to the end, and give each button a name that includes the field.

Sizes

size="sm" uses 13px text and tighter rows for cards and side panels; md is the default.

Recipes

Detail card

A deployment summary in a Card, with a status badge, a commit hash and a copyable domain.

Accessibility

  • Uses native <dl>, <dt> and <dd>, so screen readers announce terms and their values as pairs.
  • Dividers are borders, not separate elements, so they add nothing to the reading order.
  • When a value is only an icon or a color (e.g. a status dot), include text, as the Badge does.
  • Give actions in details names that include the field, e.g. aria-label="Edit email", not just "Edit".

Styling

Data attributes

AttributeOn
data-slot="description-list"DescriptionList
data-layoutDescriptionList (horizontal · stacked)
data-slot="description-term"DescriptionTerm
data-slot="description-details"DescriptionDetails

Term width

The horizontal layout reads --dl-term-width (default 33%) for the term column:

tsx
<DescriptionList className="[--dl-term-width:12rem]">…</DescriptionList>

descriptionListVariants

The tailwind-variants function behind DescriptionList, for applying the layout to your own <dl>.

API Reference

DescriptionList

Prop

Type

Also accepts every prop of <dl>.

DescriptionTerm / DescriptionDetails

No extra props. Accept every prop of <dt> and <dd>.

  • Card: frame a description list with a title.
  • Table: many records with the same fields.
  • Badge: statuses inside details.