Skip to content

Design system

Documentation

DesignComponents / Descriptions

Components / Descriptions

Beta

Descriptions

Summarize a record as responsive label and value pairs while keeping native definition-list semantics.

On this page

Examples

Responsive detail grid

Use term and definition semantics to present related read-only values.

Name
Avery Nguyen
Role
Workspace owner
Status
Active
Joined
September 12, 2026

Workspace member details

Bordered invoice summary

A subtle grid boundary helps users compare a compact set of values.

Invoice
INV-2048
Amount
$240.00
Status
Awaiting payment

Bordered invoice summary

Try the layout

Compare the responsive column count and boundary treatment using one fixture.

Project
Northstar
Owner
Avery Nguyen
Description
A longer value wraps inside its grid cell so it remains readable at narrow widths.
State
In review

Descriptions property playground

When to use

Use Descriptions on a detail view or read-only summary when each label names one value. Use Table for repeated records with the same row and column relationships, and Field for values the user can change.

Usage

import { Descriptions, DescriptionsItem } from "@phuctech/ui/components/descriptions";

<Descriptions aria-label="Member details" columns={2}>
<DescriptionsItem label="Name">Avery Nguyen</DescriptionsItem>
<DescriptionsItem label="Role">Workspace owner</DescriptionsItem>
</Descriptions>

Descriptions renders a dl; each item renders a dt and dd. Values may wrap naturally, including when a column is narrow.

API

Component API
PropTypeDefaultDescriptionConstraints
Descriptionsdl props + columns + borderedcolumns=2, bordered=falseResponsive semantic definition list.Columns are limited to 1–4 and reduce to one column on narrow screens.
DescriptionsItemdiv props + label + children—One label and its read-only value.Use concise labels; long values wrap without clipping.
columns1 | 2 | 3 | 42Maximum grid columns at wider breakpoints.The grid collapses to one column on small screens.
borderedbooleanfalseAdds shared border and padding to each item.Use when a compact set needs clearer cell separation.
className / ref / native attributesHTML element props—Forwards definition-list or item wrapper attributes.Keep description relationships semantic.

Tokens

Component tokens
TokenRoleEffective valueUsage
--space-3 / --space-4 / --space-6Grid rhythmShared spacingSeparates values while preserving a compact detail layout.
--color-border-default / --color-text-secondaryBoundaries and labelsSemantic rolesKeeps labels subordinate and borders quiet in both themes.

Accessibility

Descriptions uses the native dl, dt, and dd relationship. Add an aria-label when a surrounding heading does not already name the detail group.

Do and don’t

Do

Use clear terms and include units in values where they are not self-evident.

Don’t

Use Descriptions for editable form controls or as a substitute for a repeated data table.

  • Table compares repeated tabular records.
  • Field labels editable controls.
  • Typography defines shared text hierarchy.