Patterns

Description List

A list of read-only facts about one record, as labels and values.

Order: ORD-58213
Status: Fulfilled
Customer: Acme
Payment: Bank transfer
Placed: Mar 4, 2026
Shipped: Mar 5, 2026
Total: $1,284.00
Tracking: TRK-0123-4567

import { DescriptionItem, DescriptionList, StatusBadge } from 'ferry-ui'

export default function DescriptionListHero() {
  return (
    <DescriptionList aria-label="Order details">
      <DescriptionItem label="Order" mono>
        ORD-58213
      </DescriptionItem>
      <DescriptionItem label="Status">
        <StatusBadge tone="success" label="Fulfilled" />
      </DescriptionItem>
      <DescriptionItem label="Customer">Acme</DescriptionItem>
      <DescriptionItem label="Payment">Bank transfer</DescriptionItem>
      <DescriptionItem label="Placed">Mar 4, 2026</DescriptionItem>
      <DescriptionItem label="Shipped">Mar 5, 2026</DescriptionItem>
      <DescriptionItem label="Total">
        <span className="tabular">$1,284.00</span>
      </DescriptionItem>
      <DescriptionItem label="Tracking" mono>
        TRK-0123-4567
      </DescriptionItem>
    </DescriptionList>
  )
}

Usage guidelines#

Facts about one record. Use it for the status, the dates and the amounts of one invoice, one order or one member.
Many records are a table. To compare records by column, use Table.
Read only. For settings that the user can edit, use Form Card.
Not for a headline number. For a KPI, use Metric Card. For facts with an icon, use Info Tile.

Anatomy#

Import the two parts. The list is a <dl> element. The children of an item are its value.

Anatomy

import { DescriptionItem, DescriptionList } from 'ferry-ui'

<DescriptionList>
  <DescriptionItem label="" />
  <DescriptionItem label="" />
</DescriptionList>

The variant prop of the list sets the look. The items get the variant from the list.

Variant	Look	Use
`grid` (default)	A card of cells.	The facts at the top of a detail page.
`strip`	One row of cells.	Short values at the bottom of a card.
`rows`	Rows with the value on the right.	A side panel or the body of a card.
`inline`	Two compact columns with no frame.	A popover or a menu.

Examples#

Columns#

columns sets the number of columns of the grid and strip variants, from 1 to 4. The default is 4. The grid variant uses fewer columns on a small screen.

Owner: Maya Chen
Visibility: Private

Plan: Business
Seats: 18 of 25
Renews: Apr 1, 2026

import { DescriptionItem, DescriptionList } from 'ferry-ui'

export default function DescriptionListColumns() {
  return (
    <div className="flex flex-col gap-6">
      <DescriptionList columns={2} aria-label="Project">
        <DescriptionItem label="Owner">Maya Chen</DescriptionItem>
        <DescriptionItem label="Visibility">Private</DescriptionItem>
      </DescriptionList>
      <DescriptionList columns={3} aria-label="Subscription">
        <DescriptionItem label="Plan">Business</DescriptionItem>
        <DescriptionItem label="Seats">18 of 25</DescriptionItem>
        <DescriptionItem label="Renews">Apr 1, 2026</DescriptionItem>
      </DescriptionList>
    </div>
  )
}

Long values#

A value stays on one line. span makes a cell of the grid wider. wrap lets the text continue on more lines. mono is for an ID, a URL or a key.

Endpoint: https://hooks.example.com/v2/workspaces/acme/integrations/billing-events/receiver
Events: invoice.paid
Last delivery: 2 minutes ago
Description: Sends the paid invoices to the data warehouse of the finance team. A delivery that fails starts again for 24 hours, then the billing channel gets an alert.

import { DescriptionItem, DescriptionList } from 'ferry-ui'

const ENDPOINT = 'https://hooks.example.com/v2/workspaces/acme/integrations/billing-events/receiver'

export default function DescriptionListLongValues() {
  return (
    <DescriptionList aria-label="Webhook details">
      <DescriptionItem label="Endpoint" mono span={2}>
        <span title={ENDPOINT}>{ENDPOINT}</span>
      </DescriptionItem>
      <DescriptionItem label="Events">invoice.paid</DescriptionItem>
      <DescriptionItem label="Last delivery">2 minutes ago</DescriptionItem>
      <DescriptionItem label="Description" span="full" wrap>
        Sends the paid invoices to the data warehouse of the finance team. A delivery that fails starts again for 24
        hours, then the billing channel gets an alert.
      </DescriptionItem>
    </DescriptionList>
  )
}

Strip#

The strip variant goes at the bottom of a Card. It always shows the number of columns that you set. Keep the values short.

Design team

The workspace for product design.

The brand assets and the component library are here.

Members: 12
Projects: 7
Team ID: tm_42

import { Card, CardContent, CardDescription, CardHeader, CardTitle, DescriptionItem, DescriptionList } from 'ferry-ui'

export default function DescriptionListStrip() {
  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <div>
          <CardTitle>Design team</CardTitle>
          <CardDescription>The workspace for product design.</CardDescription>
        </div>
      </CardHeader>
      <CardContent className="text-[13px] text-foreground-light">
        The brand assets and the component library are here.
      </CardContent>
      <DescriptionList variant="strip" columns={3} aria-label="Team details">
        <DescriptionItem label="Members">12</DescriptionItem>
        <DescriptionItem label="Projects">7</DescriptionItem>
        <DescriptionItem label="Team ID" mono>
          tm_42
        </DescriptionItem>
      </DescriptionList>
    </Card>
  )
}

Rows#

In the rows variant, an item can have an icon, a hint and an href. With href, the full row is a link. divided={false} removes the line above the first row.

Acme workspace

Members: 2 pending 18
API keys: 4
API version: 2026-03-01
Region: eu-west

import { Card, CardHeader, CardTitle, DescriptionItem, DescriptionList, type LinkComponent } from 'ferry-ui'
import { Globe, KeyRound, Tag, Users } from 'lucide-react'

// In an app, the link component of your router opens the page. This one stays on the page.
const DemoLink: LinkComponent = ({ href, onClick, ...props }) => (
  <a
    href={href}
    {...props}
    onClick={(event) => {
      onClick?.(event)
      event.preventDefault()
    }}
  />
)

export default function DescriptionListRows() {
  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <CardTitle>Acme workspace</CardTitle>
      </CardHeader>
      <DescriptionList variant="rows" divided={false} aria-label="Workspace summary">
        <DescriptionItem icon={<Users />} label="Members" hint="2 pending" href="#members" linkComponent={DemoLink}>
          18
        </DescriptionItem>
        <DescriptionItem icon={<KeyRound />} label="API keys" href="#api-keys" linkComponent={DemoLink}>
          4
        </DescriptionItem>
        <DescriptionItem icon={<Tag />} label="API version" mono>
          2026-03-01
        </DescriptionItem>
        <DescriptionItem icon={<Globe />} label="Region" mono>
          eu-west
        </DescriptionItem>
      </DescriptionList>
    </Card>
  )
}

Inline#

The inline variant has no frame. Use it in a Popover or in a menu.

import {
  Button,
  DescriptionItem,
  DescriptionList,
  Popover,
  PopoverContent,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from 'ferry-ui'
import { Building2 } from 'lucide-react'

export default function DescriptionListInline() {
  return (
    <Popover>
      <PopoverTrigger asChild>
        <Button icon={<Building2 />}>Acme workspace</Button>
      </PopoverTrigger>
      <PopoverContent align="start" className="flex w-72 flex-col gap-3">
        <PopoverHeader>
          <PopoverTitle>Acme workspace</PopoverTitle>
        </PopoverHeader>
        <DescriptionList variant="inline">
          <DescriptionItem label="Plan">Business</DescriptionItem>
          <DescriptionItem label="Currency" mono>
            EUR
          </DescriptionItem>
          <DescriptionItem label="Domain" mono>
            acme.example.com
          </DescriptionItem>
          <DescriptionItem label="Owner">Maya Chen</DescriptionItem>
        </DescriptionList>
      </PopoverContent>
    </Popover>
  )
}

Loading#

Set loading on an item while its value loads. The item shows a skeleton and sets aria-busy.

Customer
Plan
Owner
Customer since

import * as React from 'react'
import { DescriptionItem, DescriptionList, Label, Switch } from 'ferry-ui'

export default function DescriptionListLoading() {
  // In an app, `loading` comes from the request that loads the record.
  const [loading, setLoading] = React.useState(true)

  return (
    <div className="flex flex-col gap-4">
      <div className="flex items-center gap-2">
        <Switch id="customer-loading" checked={loading} onCheckedChange={setLoading} />
        <Label htmlFor="customer-loading">Loading</Label>
      </div>
      <DescriptionList aria-label="Customer details">
        <DescriptionItem label="Customer" loading={loading}>
          Acme
        </DescriptionItem>
        <DescriptionItem label="Plan" loading={loading}>
          Business
        </DescriptionItem>
        <DescriptionItem label="Owner" loading={loading}>
          Maya Chen
        </DescriptionItem>
        <DescriptionItem label="Customer since" loading={loading}>
          Mar 4, 2024
        </DescriptionItem>
      </DescriptionList>
    </div>
  )
}

Empty values#

An item with no value shows a dash. The number 0 is a value.

Assignee: —
Due date: —
Notes: —
Open tasks: 0

import { DescriptionItem, DescriptionList } from 'ferry-ui'

export default function DescriptionListEmptyValues() {
  return (
    <DescriptionList aria-label="Task details">
      <DescriptionItem label="Assignee" />
      <DescriptionItem label="Due date">{null}</DescriptionItem>
      <DescriptionItem label="Notes">{''}</DescriptionItem>
      <DescriptionItem label="Open tasks">{0}</DescriptionItem>
    </DescriptionList>
  )
}

Accessibility#

The list cuts a long value. Put the full text in a title attribute.
In a row with href, the label is the text of the link. The value is its description.
Do not put a button or a second link in a row with href. The link covers the full row.

API reference#

DescriptionList also accepts each attribute of the <dl> element. DescriptionItem accepts each attribute of the <div> element.

DescriptionList#

Prop	Type	Default
`variant`	"grid" \| "inline" \| "strip" \| "rows"	grid
Look of the list (see `DescriptionListVariant`). Defaults to `grid`.
`columns`	1 \| 4 \| 3 \| 2	4
Columns of the `grid` and `strip` variants (ignored by `rows` and `inline`). Defaults to 4. `grid` is responsive: one column on phones, then 2 → `sm:2`, 3 → `sm:3`, 4 → `sm:2 lg:4`. `strip` always uses exactly this many columns, so keep it to short values.
`divided`	boolean	true
`rows` only. `true` (default) also draws a hairline above the first row, separating the list from a header above it. Set `false` when the list is the first thing in its container.
`children`	ReactNode	-
`DescriptionItem` elements.

DescriptionItem#

Prop	Type	Default
`label`Required	ReactNode	-
Short caption (1–3 words: "Status", "Issued", "Billing email"). Rendered in the `<dt>`.
`children`	ReactNode	-
The value, rendered in the `<dd>` and truncated to one line (unless `wrap`): put long text in `<span title={…}>` so the full value stays reachable. `undefined`, `null`, `false` and `''` render a muted "—" (0 is shown as is).
`mono`	boolean	false
Sets the value in the monospace font at 13px: IDs, hashes, versions, URLs, keys.
`wrap`	boolean	false
Lets a long value wrap onto several lines instead of truncating it to one: a description, a postal address, a full URL or command. Meant for the `grid` variant, paired with `span`; the other variants are built for short values. Defaults to `false`.
`icon`	ReactNode	-
`rows` only. Decorative 16px icon before the label (any `svg` is sized automatically).
`hint`	ReactNode	-
`rows` only. Muted secondary text before the value ("3 active", "of 10"). Hidden on phones.
`span`	1 \| 2 \| "full"	1
`grid` only. Cell width: `2` spans two columns from `sm` up (for long values such as a URL or an address), `'full'` spans the whole row. Defaults to 1.
`href`	string	-
`rows` only. Turns the whole row into a link to this URL (hover and focus highlight). The label is the link text and the value its accessible description. Keep other interactive elements (buttons, copy actions) out of a linked row: the link covers the whole row.
`linkComponent`	LinkComponent	-
Router link used when `href` is set. Defaults to the one from `LinkProvider` (a plain `<a>`).
`loading`	boolean	false
Shows a skeleton while the value loads and sets `aria-busy`. `rows` and `inline` keep the label; `grid` and `strip` skeleton the label too (the label stays available to screen readers).
`valueClassName`	string	-
Extra classes for the `<dd>` (e.g. `text-warning`, `flex items-center gap-1.5`).