DescriptionList · envUI Docs

Import

import { DescriptionList } from '@envsemble/envui';

Usage

DescriptionList.Root is a dl, and each DescriptionList.Item a term and its value: its label, such as Owner, and its value as children, such as text, a Link or a Badge. Name each list with aria-label where a page has several.

Facts.tsx

import { Badge, DescriptionList, Link } from '@envsemble/envui';

export default function Facts() {
  return (
    <DescriptionList.Root aria-label="Project details" style={{ inlineSize: 'min(100%, 26rem)' }}>
      <DescriptionList.Item label="Owner">Alex Morgan</DescriptionList.Item>
      <DescriptionList.Item label="Status">
        <Badge tone="success">Active</Badge>
      </DescriptionList.Item>
      <DescriptionList.Item label="Repository">
        <Link href="https://example.com/northwind">example.com/northwind</Link>
      </DescriptionList.Item>
      <DescriptionList.Item label="Last updated">4 March 2026</DescriptionList.Item>
    </DescriptionList.Root>
  );
}

Layout and size

layout is auto, the default, inline or stacked. Inline puts each label beside its value, in a column as wide as the longest label; stacked puts it above; auto is inline, and stacked where the list's own width is below 18 rem. size is sm, the default, the smaller body text, for facts beside other content, such as in a sidebar or a card, or md, body text, for a page of details.

<DescriptionList.Root layout="stacked" size="md" aria-label="Contact">
  <DescriptionList.Item label="Email">priya.shah@example.com</DescriptionList.Item>
  <DescriptionList.Item label="Address">12 Harbour Street, Northwind Bay</DescriptionList.Item>
</DescriptionList.Root>

Controls

controls on the Root is for values that hold controls, such as a Select or a Switch: each row is at least as tall as a small control, and its label sits on the control's first line. Give each control a name of its own, such as an aria-label: the label beside it isn't one.

<DescriptionList.Root controls aria-label="Sharing">
  <DescriptionList.Item label="Comments">
    <Switch aria-label="Allow comments" defaultChecked />
  </DescriptionList.Item>
</DescriptionList.Root>

Composition

The parts are the list, env-description-list, with data-layout, data-size and data-controls; each item, env-description-list-item, a div around its label, env-description-list-label, a dt, and its value, env-description-list-value, a dd. Keep headings and long paragraphs out of values, and don't nest description lists.

Accessibility

You provide

An aria-label on each list where a page has several.
A name on each control in a value: the label beside it isn't one.

envUI provides

A dl of dt and dd pairs, read as terms and their values.
Labels and values in reading order in every layout.

Props

DescriptionList.Root

A list of labelled values, the facts about one thing, such as a project's owner, status and dates: a `dl` whose items are its terms with their values.

Prop	Type	Description
`layout`Default `'auto'`	`'inline''stacked''auto'`	Where each label sits: inline, beside its value, in a column as wide as the longest label; stacked, above its value; auto, inline, stacked below 18 rem of the list's own width.
`size`Default `'sm'`	`'sm''md'`	The text size: sm, the smaller body text, for facts beside other content, such as in a sidebar or a card; md, body text, for a page of details.
`controls`Default `false`	`boolean`	The values hold controls, such as a Select or a Switch: each row is at least as tall as a small control, and its label sits on the control's first line.

Also accepts the native props of <dl>, such as ref, className and aria-* attributes.

DescriptionList.Item

One term and its value: a `div` around a `dt` and a `dd`.

Prop	Type	Description
`label`required	`ReactNode`	The term, such as Owner or Created.
`children`required	`ReactNode`	The value: text, a link, a Badge, or a control in a list with `controls`.

Also accepts the native props of <div>, such as ref, className and aria-* attributes.

Part names

Each part's class and state attributes are public and versioned, for an application's CSS to style.

env-description-list: The list of labels and values.
env-description-list-item: One label and its value.
env-description-list-label: A label.
env-description-list-value: A value.
data-controls: Present
data-layout: auto · inline · stacked
data-size: md · sm

Changelog

1.0.0: DescriptionList, with layout, size and controls.
1.0.0-prerelease.6: Stacked, the pairs stand further apart than a label from its value. Auto stacks below 18 rem of the list's width, in place of 24 rem, so a 360 px panel keeps its labels beside their values.