---
title: List
description: Ordered or unordered list with consistent spacing and marker styles
visibility: guest
draft: false
---

# List

A styled list component with consistent spacing and design tokens. Supports unordered, ordered, and unstyled lists.

## Unordered List

:::preview{title="Default unordered list"}
<x-wirekit::list>
    <x-wirekit::list.item>First item</x-wirekit::list.item>
    <x-wirekit::list.item>Second item</x-wirekit::list.item>
    <x-wirekit::list.item>Third item</x-wirekit::list.item>
</x-wirekit::list>
:::

## Ordered List

:::preview{title="Ordered list"}
<x-wirekit::list type="decimal">
    <x-wirekit::list.item>Install the package</x-wirekit::list.item>
    <x-wirekit::list.item>Run the installer</x-wirekit::list.item>
    <x-wirekit::list.item>Add the Blade directive</x-wirekit::list.item>
</x-wirekit::list>
:::

## No Markers

:::preview{title="Unstyled list"}
<x-wirekit::list type="none">
    <x-wirekit::list.item>Clean item one</x-wirekit::list.item>
    <x-wirekit::list.item>Clean item two</x-wirekit::list.item>
    <x-wirekit::list.item>Clean item three</x-wirekit::list.item>
</x-wirekit::list>
:::

## Spacing

:::preview{title="Medium spacing"}
<x-wirekit::list spacing="md">
    <x-wirekit::list.item>Item with more space</x-wirekit::list.item>
    <x-wirekit::list.item>Between each item</x-wirekit::list.item>
    <x-wirekit::list.item>For better readability</x-wirekit::list.item>
</x-wirekit::list>
:::

## Roman & Alpha Markers

For multi-level legal / academic / spec-style numbering, four additional `type` values are available — `lower-roman` (i, ii, iii), `upper-roman` (I, II, III), `lower-alpha` (a, b, c), `upper-alpha` (A, B, C). All four render as `<ol>` (ordered list semantics).

:::preview{title="Lower Roman"}
<x-wirekit::list type="lower-roman">
    <x-wirekit::list.item>Preamble</x-wirekit::list.item>
    <x-wirekit::list.item>Recitals</x-wirekit::list.item>
    <x-wirekit::list.item>Operative provisions</x-wirekit::list.item>
</x-wirekit::list>
:::

:::preview{title="Upper Alpha"}
<x-wirekit::list type="upper-alpha">
    <x-wirekit::list.item>Personal data</x-wirekit::list.item>
    <x-wirekit::list.item>Account credentials</x-wirekit::list.item>
    <x-wirekit::list.item>Usage telemetry</x-wirekit::list.item>
</x-wirekit::list>
:::

## Nested Lists — Worst-Case (mixed marker types, 5 levels)

Lists nest by composition — drop another `<x-wirekit::list>` inside a `<x-wirekit::list.item>`. Mix `type` values per level for legal / spec / outline-style hierarchies. The example below combines all five marker styles across five depth levels, replicating the "1 → a → i → ●" pattern common in legal contracts and standards documents:

:::preview{title="Five-level nested list with mixed markers"}
<x-wirekit::list type="decimal" spacing="md">
    <x-wirekit::list.item>
        Top-level numbered section
        <x-wirekit::list type="upper-alpha" spacing="sm">
            <x-wirekit::list.item>
                Capital-letter sub-section
                <x-wirekit::list type="lower-roman" spacing="sm">
                    <x-wirekit::list.item>
                        Lower-roman clause
                        <x-wirekit::list type="lower-alpha" spacing="none">
                            <x-wirekit::list.item>
                                Lower-letter sub-clause
                                <x-wirekit::list type="disc" spacing="none">
                                    <x-wirekit::list.item>Bullet detail one</x-wirekit::list.item>
                                    <x-wirekit::list.item>Bullet detail two</x-wirekit::list.item>
                                </x-wirekit::list>
                            </x-wirekit::list.item>
                            <x-wirekit::list.item>Another lower-letter sub-clause</x-wirekit::list.item>
                        </x-wirekit::list>
                    </x-wirekit::list.item>
                    <x-wirekit::list.item>Second lower-roman clause</x-wirekit::list.item>
                </x-wirekit::list>
            </x-wirekit::list.item>
            <x-wirekit::list.item>Second capital-letter sub-section</x-wirekit::list.item>
        </x-wirekit::list>
    </x-wirekit::list.item>
    <x-wirekit::list.item>Second top-level section (no nesting)</x-wirekit::list.item>
    <x-wirekit::list.item>
        Third top-level section
        <x-wirekit::list type="upper-roman" spacing="none">
            <x-wirekit::list.item>Major roman point</x-wirekit::list.item>
            <x-wirekit::list.item>Another major roman point</x-wirekit::list.item>
        </x-wirekit::list>
    </x-wirekit::list.item>
</x-wirekit::list>
:::

Each level is a fresh `<x-wirekit::list type="…">` — markers, spacing, and the underlying tag (`<ol>` / `<ul>`) all resolve from the inner component's own `type` prop. Markdown's flat list-syntax can't express this; pure `<x-wirekit::list>` composition can.

## Props — List

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | string | `'disc'` | Marker type: `disc`, `decimal`, `none`, `lower-roman`, `upper-roman`, `lower-alpha`, `upper-alpha` |
| `spacing` | string | `'sm'` | Item spacing: `none`, `sm`, `md` |
| `as` | string\|null | `null` | Override element (auto: `ul` for `disc` / `none`, `ol` for ordered types) |
| `scope` | string\|null | `null` | Scoped personalization name |

## Props — List Item

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scope` | string\|null | `null` | Scoped personalization name |

## Keyboard Interaction

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

## Pitfalls

- **Don't use a list for layout.** Reach for `<x-wirekit::stack>` or `<x-wirekit::row>`. Lists carry semantic role="list" and screen readers announce item count — misleading for non-list content.

## Design Tokens

The list and list-item primitives are layout wrappers — they apply structural classes (spacing utilities, semantic `<ul>` / `<ol>` / `<li>` elements) without referencing color or sizing tokens directly. Item content (icons, badges, links) inherits its tokens from the surrounding [Text](/components/text), [Icon component](/components/icon#design-tokens), and [Link component](/components/link#design-tokens).