# DescriptionList

> Key to value pairs such as account details or contract metadata, using native <dl>.

Category: Data display · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/description-list

Use DescriptionList to show attributes of one thing: an organisation’s settings, a contract’s parties and dates, an integration’s configuration. Choose horizontal for detail pages, vertical for narrow panels and grid for summary headers. Every layout stacks on phones.

## Import

```tsx
import { DescriptionList, DescriptionListItem } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Horizontal

```tsx
import { Badge, DescriptionList, DescriptionListItem } from '@bindshq/stance-react';

export function Basic() {
  return (
    <DescriptionList>
      <DescriptionListItem term="Contract">MSA-2026-014</DescriptionListItem>
      <DescriptionListItem term="Counterparty">Northwind Ltd</DescriptionListItem>
      <DescriptionListItem term="Status">
        <Badge tone="success" dot>
          Signed
        </Badge>
      </DescriptionListItem>
      <DescriptionListItem term="Effective date">6 November 2026</DescriptionListItem>
      <DescriptionListItem term="Owner">Priya Raman, Legal</DescriptionListItem>
    </DescriptionList>
  );
}
```

### Grid summary

```tsx
import { DescriptionList } from '@bindshq/stance-react';

export function Grid() {
  return (
    <DescriptionList
      layout="grid"
      columns={4}
      items={[
        { term: 'Mailboxes', details: '312' },
        { term: 'Templates', details: '24' },
        { term: 'Relay', details: 'smtp.binds.si' },
        { term: 'Last sync', details: '4 minutes ago' },
      ]}
    />
  );
}
```

### Vertical

```tsx
import { DescriptionList } from '@bindshq/stance-react';

export function Vertical() {
  return (
    <div style={{ maxWidth: 280 }}>
      <DescriptionList
        layout="vertical"
        items={[
          { term: 'Billing contact', details: 'finance@binds.si' },
          { term: 'Billing address', details: '1 Canal Street, Manchester M1 3HE' },
          { term: 'VAT number', details: 'GB 123 4567 89' },
        ]}
      />
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| DescriptionList | `layout` | `'horizontal' \| 'vertical' \| 'grid'` | `'horizontal'` | Arrangement of terms and details. |
| DescriptionList | `columns` | `2 \| 3 \| 4` | `2` | Columns for the grid layout. |
| DescriptionList | `dividers` | `boolean` | `true for horizontal` | Lines between rows. |
| DescriptionList | `items` | `{ term: ReactNode; details: ReactNode; key?: Key }[]` | None | Shorthand to render pairs from data. |
| DescriptionListItem | `term` (required) | `ReactNode` | None | The label (<dt>). |
| DescriptionListItem | `children` | `ReactNode` | None | The value (<dd>). |

## Accessibility

- Uses native <dl>, <dt> and <dd>, which screen readers announce as term and definition pairs.
- Pairs are grouped in <div> elements, which HTML allows inside <dl>.
- Long values wrap instead of overflowing.

## Guidelines

**Do**

- Use consistent, short terms.
- Show "None" for empty values rather than omitting the row.

**Don’t**

- Use for comparisons across many items; use Table.

## Related

- https://stanceui.com/components/table
- https://stanceui.com/components/card