# Description List

Labeled values, such as the details of a record.

Source: [description-list.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/description-list.tsx)

```tsx
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
import {
  DescriptionList,
  DescriptionListDetails,
  DescriptionListItem,
  DescriptionListTerm,
} from "@/components/ui/description-list";
import { Status } from "@/components/ui/status";
import { people } from "@/examples/data";

export default function DescriptionListInvoice() {
  const ada = people[0];
  return (
    <DescriptionList className="max-w-md">
      <DescriptionListItem>
        <DescriptionListTerm>Status</DescriptionListTerm>
        <DescriptionListDetails>
          <Status variant="success">Paid</Status>
        </DescriptionListDetails>
      </DescriptionListItem>
      <DescriptionListItem>
        <DescriptionListTerm>Customer</DescriptionListTerm>
        <DescriptionListDetails className="flex items-center gap-2">
          <Avatar size="sm">
            <AvatarImage src={ada.image} alt="" />
            <AvatarFallback>{ada.initials}</AvatarFallback>
          </Avatar>
          {ada.name}
        </DescriptionListDetails>
      </DescriptionListItem>
      <DescriptionListItem>
        <DescriptionListTerm>Amount</DescriptionListTerm>
        <DescriptionListDetails>$6,300.00</DescriptionListDetails>
      </DescriptionListItem>
      <DescriptionListItem>
        <DescriptionListTerm>Invoice</DescriptionListTerm>
        <DescriptionListDetails className="font-mono">INV-0042</DescriptionListDetails>
      </DescriptionListItem>
      <DescriptionListItem>
        <DescriptionListTerm>Issued</DescriptionListTerm>
        <DescriptionListDetails>October 4, 2026</DescriptionListDetails>
      </DescriptionListItem>
    </DescriptionList>
  );
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/description-list
```

## Usage

```tsx
import {
  DescriptionList,
  DescriptionListDetails,
  DescriptionListItem,
  DescriptionListTerm,
} from "@/components/ui/description-list";

export function InvoiceDetails() {
  return (
    <DescriptionList>
      <DescriptionListItem>
        <DescriptionListTerm>Amount</DescriptionListTerm>
        <DescriptionListDetails>$6,300.00</DescriptionListDetails>
      </DescriptionListItem>
      <DescriptionListItem>
        <DescriptionListTerm>Issued</DescriptionListTerm>
        <DescriptionListDetails>October 4, 2026</DescriptionListDetails>
      </DescriptionListItem>
    </DescriptionList>
  );
}
```

Wrap each term and its value in a `DescriptionListItem`. A term can have more than one
`DescriptionListDetails`.

## Composition

- `DescriptionList`
  - `DescriptionListItem`
    - `DescriptionListTerm`
    - `DescriptionListDetails`

## Examples

### Vertical

`orientation="vertical"` puts each term above its value. Add `grid-cols-*` for columns.

```tsx
import {
  DescriptionList,
  DescriptionListDetails,
  DescriptionListItem,
  DescriptionListTerm,
} from "@/components/ui/description-list";

const details = [
  { term: "Region", details: "Frankfurt" },
  { term: "Instance", details: "4 vCPU, 8 GB" },
  { term: "IP address", details: "203.0.113.24" },
  { term: "Uptime", details: "41 days" },
];

export default function DescriptionListVertical() {
  return (
    <DescriptionList orientation="vertical" className="max-w-md grid-cols-2">
      {details.map((item) => (
        <DescriptionListItem key={item.term}>
          <DescriptionListTerm>{item.term}</DescriptionListTerm>
          <DescriptionListDetails>{item.details}</DescriptionListDetails>
        </DescriptionListItem>
      ))}
    </DescriptionList>
  );
}
```

### Responsive

`orientation="responsive"` stacks the items when the list itself is narrow.

```tsx
import {
  DescriptionList,
  DescriptionListDetails,
  DescriptionListItem,
  DescriptionListTerm,
} from "@/components/ui/description-list";

export default function DescriptionListResponsive() {
  return (
    <DescriptionList orientation="responsive" className="max-w-xl">
      <DescriptionListItem>
        <DescriptionListTerm>Name</DescriptionListTerm>
        <DescriptionListDetails>Driftwood Coffee</DescriptionListDetails>
      </DescriptionListItem>
      <DescriptionListItem>
        <DescriptionListTerm>Billing email</DescriptionListTerm>
        <DescriptionListDetails>accounts@example.com</DescriptionListDetails>
      </DescriptionListItem>
      <DescriptionListItem>
        <DescriptionListTerm>Address</DescriptionListTerm>
        <DescriptionListDetails>
          18 Harbor Lane
          <br />
          Portland, ME 04101
        </DescriptionListDetails>
      </DescriptionListItem>
    </DescriptionList>
  );
}
```

### Dividers

`divided` draws a line between items. Use it with a single column.

```tsx
import { Badge } from "@/components/ui/badge";
import {
  DescriptionList,
  DescriptionListDetails,
  DescriptionListItem,
  DescriptionListTerm,
} from "@/components/ui/description-list";

export default function DescriptionListDivided() {
  return (
    <DescriptionList divided className="max-w-md">
      <DescriptionListItem>
        <DescriptionListTerm>Plan</DescriptionListTerm>
        <DescriptionListDetails>
          <Badge>Team</Badge>
        </DescriptionListDetails>
      </DescriptionListItem>
      <DescriptionListItem>
        <DescriptionListTerm>Seats</DescriptionListTerm>
        <DescriptionListDetails>12 of 25</DescriptionListDetails>
      </DescriptionListItem>
      <DescriptionListItem>
        <DescriptionListTerm>Renews</DescriptionListTerm>
        <DescriptionListDetails>April 1, 2027</DescriptionListDetails>
      </DescriptionListItem>
    </DescriptionList>
  );
}
```

## Props

| Part | Extends |
| --- | --- |
| `DescriptionList` | `<dl>` |
| `DescriptionListItem` | `<div>` |
| `DescriptionListTerm` | `<dt>` |
| `DescriptionListDetails` | `<dd>` |

### DescriptionList

| Prop           | Type                                         | Description             |
| -------------- | -------------------------------------------- | ----------------------- |
| `orientation?` | `"horizontal" \| "responsive" \| "vertical"` | Default: `"horizontal"` |
| `divided?`     | `boolean`                                    | Default: `false`        |