Tree View

A hierarchical list for displaying nested data structures — file trees, category hierarchies, organization charts. Implements the full WAI-ARIA Tree View pattern with keyboard navigation.

Basic Usage

<x-wirekit::tree-view>
    <x-wirekit::tree-view.node label="src" expanded>
        <x-wirekit::tree-view.node label="components">
            <x-wirekit::tree-view.node label="Button.php" />
            <x-wirekit::tree-view.node label="Input.php" />
        </x-wirekit::tree-view.node>
        <x-wirekit::tree-view.node label="utils">
            <x-wirekit::tree-view.node label="helpers.php" />
        </x-wirekit::tree-view.node>
    </x-wirekit::tree-view.node>
    <x-wirekit::tree-view.node label="tests">
        <x-wirekit::tree-view.node label="Feature">
            <x-wirekit::tree-view.node label="ButtonTest.php" />
        </x-wirekit::tree-view.node>
    </x-wirekit::tree-view.node>
</x-wirekit::tree-view>

With Icons

Pass semantic icon aliases to indicate file types:

<x-wirekit::tree-view>
    <x-wirekit::tree-view.node label="Documents" icon="menu" expanded>
        <x-wirekit::tree-view.node label="Report.pdf" icon="edit" />
        <x-wirekit::tree-view.node label="Budget.xlsx" icon="edit" />
    </x-wirekit::tree-view.node>
    <x-wirekit::tree-view.node label="Images" icon="menu">
        <x-wirekit::tree-view.node label="photo.jpg" icon="eye" />
    </x-wirekit::tree-view.node>
</x-wirekit::tree-view>

Pre-expanded Nodes

Use the expanded prop to open branch nodes by default — great for surfacing the most relevant level of a hierarchy without forcing a click:

<x-wirekit::tree-view>
    <x-wirekit::tree-view.node label="Workspace" expanded>
        <x-wirekit::tree-view.node label="Pinned" expanded>
            <x-wirekit::tree-view.node label="Dashboard" />
            <x-wirekit::tree-view.node label="Reports" />
        </x-wirekit::tree-view.node>
        <x-wirekit::tree-view.node label="Archive">
            <x-wirekit::tree-view.node label="2024" />
            <x-wirekit::tree-view.node label="2023" />
        </x-wirekit::tree-view.node>
    </x-wirekit::tree-view.node>
</x-wirekit::tree-view>

Handling Selection

Listen to the tree-node-select event to respond to user selections. It fires for a click and for keyboard activation alike, so one handler covers both:

<x-wirekit::tree-view @tree-node-select="console.log($event.detail.label)">
    <x-wirekit::tree-view.node label="Option A" />
    <x-wirekit::tree-view.node label="Option B" />
</x-wirekit::tree-view>

Dynamic Data

Build trees from a Livewire property using recursive Blade:

// In your Livewire component
public array $tree = [
    ['label' => 'src', 'children' => [
        ['label' => 'App.php'],
        ['label' => 'routes', 'children' => [
            ['label' => 'web.php'],
        ]],
    ]],
];

{{-- In your Blade view --}}
<x-wirekit::tree-view>
    @foreach($tree as $node)
        @include('partials.tree-node', ['node' => $node])
    @endforeach
</x-wirekit::tree-view>

{{-- partials/tree-node.blade.php --}}
<x-wirekit::tree-view.node :label="$node['label']">
    @if(!empty($node['children']))
        @foreach($node['children'] as $child)
            @include('partials.tree-node', ['node' => $child])
        @endforeach
    @endif
</x-wirekit::tree-view.node>

Tree View Props

Node Props

Slots

Events

Accessibility

• Container uses role="tree" — screen readers announce "tree"
• Each node uses role="treeitem" on the row that receives focus — a screen reader announces the role and state of the focused element, so the two have to be the same element
• Branch nodes have aria-expanded="true" or "false" — state announced on focus
• Nested children wrapped in role="group", tied back to their branch row with aria-owns — screen readers convey nesting
• Decorative chevrons/spacers marked aria-hidden="true"
• Focus ring visible on keyboard navigation
• Full keyboard pattern: arrows, Home, End, Enter, Space, and type-ahead

Keyboard Interaction

The tree view implements the full WAI-ARIA Tree View keyboard pattern:

Pitfalls

• Don't put more than ~500 nodes in a single tree. WAI-ARIA Authoring Practices warn that virtual focus management degrades for large trees. Lazy-load child nodes on expand.
• Don't use <x-wirekit::tree-view> for non-hierarchical data. Flat lists belong in <x-wirekit::data-list>; the tree's aria-level semantics will mislead screen readers.

Design Tokens

Customization

This component reads no config/wirekit.php keys — every option is a prop. Style it through the design tokens above, or scope a variant with the scope prop.

An empty 'tree-view' => [] block in the config is not an override point: pasting one changes nothing.

Further Reading

• WAI-ARIA Tree View Pattern
• MDN: role="tree"
• MDN: role="treeitem"