List

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

Unordered List

Default unordered list

First item
Second item
Third item

<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

Ordered list

Install the package
Run the installer
Add the Blade directive

<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

Unstyled list

Clean item one
Clean item two
Clean item three

<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>

Every list.item, link and text is a component of its own, and a component costs a render: a list of a thousand rows, each with a link and a note, renders three thousand of them. Pass the rows as data with items and the list draws them all in its own render. A row is its text, or an array with the text, the href it links to and a short meta note after it, set small and muted:

A list drawn from data

Shipping rules for the winter season Updated today
Returns within thirty days Since March
A row that is only its text

<x-wirekit::list type="none" :items="[
    ['text' => 'Shipping rules for the winter season', 'href' => '#', 'meta' => 'Updated today'],
    ['text' => 'Returns within thirty days', 'meta' => 'Since March'],
    'A row that is only its text',
]" />

// In the component that renders the page: the rows as data, built once
$rows = $articles->map(fn (Article $article): array => [
    'text' => $article->title,
    'href' => route('articles.show', $article),
    'meta' => $article->updated_at->diffForHumans(),
])->all();

The link and the note carry exactly the classes link and text render with, your personalization of those two included. An href the browser would run as script, javascript: and the like, leaves its row as text. Rows from items come first, and anything in the slot follows them. For a row that needs more than a text, a link and a note, write a list.item for it.

Spacing

Medium spacing

Item with more space
Between each item
For better readability

<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).

Lower Roman

Preamble
Recitals
Operative provisions

<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>

Upper Alpha

Personal data
Account credentials
Usage telemetry

<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:

Five-level nested list with mixed markers

Top-level numbered section
1. Capital-letter sub-section
  1. Lower-roman clause
    1. Lower-letter sub-clause
      - Bullet detail one
      - Bullet detail two
    2. Another lower-letter sub-clause
  2. Second lower-roman clause
2. Second capital-letter sub-section
Second top-level section (no nesting)
Third top-level section
1. Major roman point
2. Another major roman point

<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)
`items`	array\|Collection\|null	`null`	Rows as data, drawn in one render: a string, or an array with `text`, `href` and `meta`. See Long Lists From Data
`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, Icon component, and Link component.

List

Was this page helpful?