Data List – React component

Show the details of one record as label and value rows, side by side or stacked.

Subscription

Plan: Pro, billed yearly
Renewal: March 1, 2027
Seats: 12 of 20 in use
Billing email: billing@northlight.studio

"use client";

import {
  Card,
  CardHeader,
  CardPanel,
  CardTitle,
} from "@/siteplane/components/card";
import {
  DataList,
  DataListItem,
  DataListLabel,
  DataListValue,
} from "@/siteplane/components/data-list";

const subscription = [
  { label: "Plan", value: "Pro, billed yearly" },
  { label: "Renewal", value: "March 1, 2027" },
  { label: "Seats", value: "12 of 20 in use" },
  { label: "Billing email", value: "billing@northlight.studio" },
];

export default function Example() {
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Subscription</CardTitle>
      </CardHeader>
      <CardPanel>
        <DataList>
          {subscription.map((detail) => (
            <DataListItem key={detail.label}>
              <DataListLabel>{detail.label}</DataListLabel>
              <DataListValue>{detail.value}</DataListValue>
            </DataListItem>
          ))}
        </DataList>
      </CardPanel>
    </Card>
  );
}

Installation

pnpm dlx shadcn@4.18.0 add @siteplane/data-list

Complete the one-time setup first. Registry JSON lists source files and dependencies.

For this page’s examples, also install:

pnpm dlx shadcn@4.18.0 add @siteplane/badge @siteplane/card @siteplane/code @siteplane/separator

Usage

import {
  DataList,
  DataListItem,
  DataListLabel,
  DataListValue,
} from "@/siteplane/components/data-list";

<DataList>
  <DataListItem>
    <DataListLabel>Plan</DataListLabel>
    <DataListValue>Pro, billed yearly</DataListValue>
  </DataListItem>
</DataList>;

Composition

DataList
└── DataListItem
    ├── DataListLabel
    └── DataListValue

DataList renders a description list, dl. Each DataListItem groups one DataListLabel, a dt, with its DataListValue, a dd, so assistive technologies read every label with its value.

The labels share one column, beside their values. It is as wide as the widest label, up to 40% of the list, and the values take the rest, 16 px after it. A longer label wraps inside the column. Set --data-list-label-width on DataList for a fixed column, so that lists one under another line up:

<DataList className="[--data-list-label-width:8rem]">

Labels take the quieter text at the regular weight and values the primary text. Long values, such as a URL or an ID without spaces, wrap within their column and never widen the list.

Dividers

Set dividers to draw the hairline that cards and separators draw between two items, with 12 px above and below it. The first item keeps no space above its content and the last item none below it, so the text lines up with the content around the list, as in this card. A value can hold inline parts, such as a Code, a Badge or a time element.

Connection

Fields: 1,248 in 12 folders
Last sync: Today, 4:20 PM
Agent: Claude Code on a MacBook Pro
Package: 1.1.0 1.2.0 available

"use client";

import { Badge } from "@/siteplane/components/badge";
import {
  Card,
  CardHeader,
  CardPanel,
  CardTitle,
} from "@/siteplane/components/card";
import { Code } from "@/siteplane/components/code";
import {
  DataList,
  DataListItem,
  DataListLabel,
  DataListValue,
} from "@/siteplane/components/data-list";
import { Separator } from "@/siteplane/components/separator";

export default function Example() {
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Connection</CardTitle>
      </CardHeader>
      <Separator role="presentation" />
      <CardPanel>
        <DataList dividers>
          <DataListItem>
            <DataListLabel>Fields</DataListLabel>
            <DataListValue>1,248 in 12 folders</DataListValue>
          </DataListItem>
          <DataListItem>
            <DataListLabel>Last sync</DataListLabel>
            <DataListValue>
              <time dateTime="2026-10-15T16:20">Today, 4:20 PM</time>
            </DataListValue>
          </DataListItem>
          <DataListItem>
            <DataListLabel>Agent</DataListLabel>
            <DataListValue>Claude Code on a MacBook Pro</DataListValue>
          </DataListItem>
          <DataListItem>
            <DataListLabel>Package</DataListLabel>
            <DataListValue>
              <Code>1.1.0</Code>{" "}
              <Badge variant="warning">1.2.0 available</Badge>
            </DataListValue>
          </DataListItem>
        </DataList>
      </CardPanel>
    </Card>
  );
}

Vertical

Set orientation="vertical" to place each label above its value, for a narrow column such as a side panel, or for long values. The label sits 4 px above its value and the items are 16 px apart.

Company: Northlight Studio Inc.
Billing address: 500 Market Street, San Francisco, CA 94105
Tax ID: 94-1234567

"use client";

import {
  DataList,
  DataListItem,
  DataListLabel,
  DataListValue,
} from "@/siteplane/components/data-list";

export default function Example() {
  return (
    <DataList className="w-full max-w-md" orientation="vertical">
      <DataListItem>
        <DataListLabel>Company</DataListLabel>
        <DataListValue>Northlight Studio Inc.</DataListValue>
      </DataListItem>
      <DataListItem>
        <DataListLabel>Billing address</DataListLabel>
        <DataListValue>
          500 Market Street, San Francisco, CA 94105
        </DataListValue>
      </DataListItem>
      <DataListItem>
        <DataListLabel>Tax ID</DataListLabel>
        <DataListValue>94-1234567</DataListValue>
      </DataListItem>
    </DataList>
  );
}

API reference

Component properties
Prop	Type	Default	Description
`DataList.orientation`	`DataListOrientation: horizontal \| vertical`	`horizontal`	horizontal sets each label beside its value, in one label column; vertical sets each label above its value.
`DataList.dividers`	`boolean`	`false`	Draws a hairline between two items, with 12 px above and below it.
`DataList --data-list-label-width`	`CSS length`	`fit-content(40%)`	Width of the horizontal label column: as wide as the widest label, up to 40% of the list. Set it on DataList, for example with className="[--data-list-label-width:8rem]".
`DataListItem`	`div props`	`—`	One label and its value.
`DataListLabel`	`dt props`	`—`	The name of a value.
`DataListValue`	`dd props`	`—`	The value: text or inline parts, such as a Badge, a Code or a link.

DataListProps extends native dl props; DataListItem, DataListLabel and DataListValue accept native div, dt and dd props. All parts accept refs, children and string className. DataListOrientation is exported. The list holds no state and renders on the server.

Read the installed source.

Usage notes

Use a Data List for the properties of one record, such as an account, a deployment or an invoice. Use Table when people compare, sort or filter many records, and Settings List when every row holds a control that changes a setting.