---
title: Data List
description: Key-value data display list
visibility: guest
draft: false
---

# Data List

Semantic key-value pairs rendered as a native `<dl>` (definition list). Ideal for displaying record details, settings summaries, or any structured label + value content.

## Basic Usage

:::preview{title="Horizontal data list (default)"}
<x-wirekit::data-list>
    <x-wirekit::data-list.item label="Name">John Doe</x-wirekit::data-list.item>
    <x-wirekit::data-list.item label="Email">john.doe@mail</x-wirekit::data-list.item>
    <x-wirekit::data-list.item label="Plan">Pro ($29/mo)</x-wirekit::data-list.item>
    <x-wirekit::data-list.item label="Joined">June 1, 2024</x-wirekit::data-list.item>
</x-wirekit::data-list>
:::

## Layouts

### Horizontal (default)

Labels on the left, values on the right. Items separated by dividers:

```blade
<x-wirekit::data-list layout="horizontal">
    <x-wirekit::data-list.item label="Status">Active</x-wirekit::data-list.item>
</x-wirekit::data-list>
```

### Stacked

Labels above values, each item spaced vertically:

:::preview{title="Stacked layout"}
<x-wirekit::data-list layout="stacked">
    <x-wirekit::data-list.item label="Description">A long description that wraps naturally in a stacked layout without being constrained by a side-by-side arrangement.</x-wirekit::data-list.item>
    <x-wirekit::data-list.item label="Category">Engineering</x-wirekit::data-list.item>
</x-wirekit::data-list>
:::

### Grid

Two-column grid on desktop, stacked on mobile:

:::preview{title="Grid layout"}
<x-wirekit::data-list layout="grid">
    <x-wirekit::data-list.item label="First Name">John</x-wirekit::data-list.item>
    <x-wirekit::data-list.item label="Last Name">Doe</x-wirekit::data-list.item>
    <x-wirekit::data-list.item label="Email">john.doe@mail</x-wirekit::data-list.item>
    <x-wirekit::data-list.item label="Phone">+1 (555) 123-4567</x-wirekit::data-list.item>
</x-wirekit::data-list>
:::

## Rich Values

The value slot accepts any content, including other WireKit components:

:::preview{title="Rich values"}
<x-wirekit::data-list>
    <x-wirekit::data-list.item label="Status"><x-wirekit::badge intent="success">Active</x-wirekit::badge></x-wirekit::data-list.item>
    <x-wirekit::data-list.item label="Plan"><x-wirekit::badge>Pro</x-wirekit::badge></x-wirekit::data-list.item>
    <x-wirekit::data-list.item label="Next billing">December 1, 2024</x-wirekit::data-list.item>
</x-wirekit::data-list>
:::

## Props

### Container

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `layout` | `string` | `'horizontal'` | `horizontal` \| `stacked` \| `grid` |
| `scope` | `string` | `null` | Scoped personalization key |

### Item

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `null` | The label (key) for this entry |
| `scope` | `string` | `null` | Scoped personalization key |

## Accessibility

- Uses native `<dl>`, `<dt>`, `<dd>` HTML elements — screen readers announce content as a definition list.
- No ARIA attributes needed — the semantic HTML provides the accessibility contract.
- Label text styled with muted color but readable at WCAG AA contrast ratios via design tokens.

## Keyboard Interaction

This component is purely presentational and does not respond to keyboard input.

## Pitfalls

- **Don't pass items with HTML in label/value.** The component HTML-escapes both — passing `<strong>` renders as text. Use named slots when you need rich content per row.

## Design Tokens

| Token | Usage |
| --- | --- |
| `--font-wk-sans` | Font family |
| `--text-wk-md` | Body text size |
| `--text-wk-sm` | Label text size |
| `--color-wk-text` | Value text color |
| `--color-wk-text-muted` | Label text color |
| `--color-wk-border-subtle` | Divider color (horizontal layout) |
| `--padding-wk-y-sm` | Item vertical padding |
| `--font-wk-heading-weight` | Label font weight |