Shadcn Data List for React and Tailwind

Installation

bunx --bun shadcn@latest add https://kit.dev/r/data-list.json

pnpm dlx shadcn@latest add https://kit.dev/r/data-list.json

npx shadcn@latest add https://kit.dev/r/data-list.json

yarn shadcn@latest add https://kit.dev/r/data-list.json

bun add @ark-ui/react

pnpm add @ark-ui/react

npm install @ark-ui/react

yarn add @ark-ui/react

"use client";

import { ark } from "@ark-ui/react/factory";
import type React from "react";
import { cn } from "@/lib/utils";

export interface DataListProps extends React.ComponentProps<typeof ark.dl> {
  /**
   * Layout of each item. The list itself is always stacked.
   * `horizontal` places label and value in a row.
   * `vertical` stacks label above value.
   *
   * @default "horizontal"
   */
  orientation?: "horizontal" | "vertical";
}

export const DataList = (props: DataListProps) => {
  const { orientation = "horizontal", className, children, ...rest } = props;

  return (
    <ark.dl
      className={cn(
        "group/data-list",
        "flex flex-col gap-1",
        "text-sm",
        className
      )}
      data-orientation={orientation}
      data-slot="data-list"
      {...rest}
    >
      {children}
    </ark.dl>
  );
};

export const DataListItem = (props: React.ComponentProps<typeof ark.div>) => {
  const { className, ...rest } = props;

  return (
    <ark.div
      className={cn(
        "flex gap-4 py-2",
        "group-data-[orientation=horizontal]/data-list:flex-row group-data-[orientation=horizontal]/data-list:items-center",
        "group-data-[orientation=vertical]/data-list:flex-col group-data-[orientation=vertical]/data-list:gap-1",
        className
      )}
      data-slot="data-list-item"
      {...rest}
    />
  );
};

export const DataListItemLabel = (
  props: React.ComponentProps<typeof ark.dt>
) => {
  const { className, ...rest } = props;

  return (
    <ark.dt
      className={cn(
        "min-w-24 shrink-0",
        "font-medium text-muted-foreground",
        "group-data-[orientation=vertical]/data-list:min-w-0",
        className
      )}
      data-slot="data-list-item-label"
      {...rest}
    />
  );
};

export const DataListItemValue = (
  props: React.ComponentProps<typeof ark.dd>
) => {
  const { className, ...rest } = props;

  return (
    <ark.dd
      className={cn("flex-1", "text-foreground", className)}
      data-slot="data-list-item-value"
      {...rest}
    />
  );
};

Anatomy

DataList
└── DataListItem
    ├── DataListItemLabel
    └── DataListItemValue

shadcn.io Data List is a composed dl / div / dt / dd (Ark factory), not a Zag machine. There is no context hook or root provider. Each item is a grouping div around one label (dt) and one or more values (dd) — valid HTML5.

Usage

import {
  DataList,
  DataListItem,
  DataListItemLabel,
  DataListItemValue,
} from "@/components/ui/data-list";

<DataList>
  <DataListItem>
    <DataListItemLabel>Name</DataListItemLabel>
    <DataListItemValue>John Doe</DataListItemValue>
  </DataListItem>
  <DataListItem>
    <DataListItemLabel>Email</DataListItemLabel>
    <DataListItemValue>[email protected]</DataListItemValue>
  </DataListItem>
</DataList>

The list of items is always stacked (flex-col). orientation is the item axis: horizontal (default) puts label and value in a row; vertical stacks the label above the value.

Orientation

Horizontal

Label and value sit on one row. Labels use a min-w-24 column so values line up.

Vertical

Label above value. Label min-width is cleared.

Examples

Info tip

Put a labeled Toggle Tooltip on the label for extra help. Decorative icons should be aria-hidden="true".

Separator

Use divide-y on DataList to draw a line between items.

With badge

DataListItemValue can hold rich content such as Badge, links, or Status.

Guides

Orientation

orientation does not change whether items stack. It only changes each item:

Set it on DataList. Items read it from data-orientation via group-data-[orientation=…].

Separators

There is no separator part. Add className="divide-y" (or divide-y divide-border) on DataList. Item py-2 keeps space around the line.

Column width

Override the label column on items or labels:

<DataListItemLabel className="min-w-32">Account ID</DataListItemLabel>

In vertical orientation the built-in min-w-24 is already cleared.

Data List vs Table vs Description list

asChild

asChild comes from Ark’s factory. Merge a part onto a single child:

<DataListItemValue asChild>
  <a href="mailto:[email protected]">[email protected]</a>
</DataListItemValue>

API Reference

shadcn.io Data List is composed dl / div / dt / dd (Ark factory), not a Zag machine. There is no context hook or root provider.

asChild merges props onto a single child element.

DataList

Root definition list. Renders a dl.

Native dl attributes pass through.

Spacing is flex flex-col gap-1. Text is text-sm.

DataListItem

One label/value group. Renders a div (HTML5 grouping wrapper inside dl).

Uses flex gap-4 py-2. Horizontal: flex-row items-center. Vertical: flex-col gap-1.

DataListItemLabel

Term. Renders a dt.

min-w-24 shrink-0 in horizontal orientation; min-w-0 when the root is vertical. Text is font-medium text-muted-foreground.

DataListItemValue

Definition. Renders a dd. One item may contain more than one value.

Uses flex-1 text-foreground.

DataListProps

Props of DataList: dl attributes plus orientation.

Accessibility

Uses native description list semantics (dl / dt / dd). Keep one label per item; extra DataListItemValues are extra definitions for that term.

• Icon-only controls in a label (info buttons) need aria-label. Decorative icons: aria-hidden="true".
• Do not put interactive controls only in a dt if the value is the action — the value can hold links and buttons.
• DataListItem as a div inside dl is allowed in HTML5 when it wraps dt / dd.

Keyboard support

The list is not a composite widget. Links and buttons inside labels or values participate in the normal tab order.