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

Simple file tree

src
- components
  - Button.php
  - Input.php
- utils
  - helpers.php
tests
- Feature
  - ButtonTest.php

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

Tree with icons

Documents
- Report.pdf
- Budget.xlsx
Images
- photo.jpg

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

Pre-expanded branches

Workspace
- Pinned
  - Dashboard
  - Reports
- Archive
  - 2024
  - 2023

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

<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

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

Node Props

Prop	Type	Default	Description
`label`	string	`''`	Node display text
`icon`	string\|null	`null`	Semantic icon alias
`expanded`	bool	`false`	Whether branch node starts expanded
`selected`	bool	`false`	Whether node starts selected
`scope`	string\|null	`null`	Scoped personalization key

Slots

Slot	Purpose
default	Child nodes (makes this a branch node)

Events

Event	Detail	Description
`tree-node-select`	`{ label: string }`	Dispatched when Enter/Space is pressed on a focused node

Accessibility

Container uses role="tree" — screen readers announce "tree"
Each node uses role="treeitem" — announced as tree item
Branch nodes have aria-expanded="true" or "false" — state announced on focus
Nested children wrapped in role="group" — 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

Keyboard Interaction

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

Key	Action
`Tab`	Move focus into the tree
`ArrowDown` / `ArrowUp`	Move to the next / previous visible node
`ArrowRight` (collapsed branch)	Expand the branch
`ArrowRight` (expanded branch)	Move focus to the first child
`ArrowLeft` (expanded branch)	Collapse the branch
`ArrowLeft` (collapsed leaf)	Move focus to the parent
`Home` / `End`	Jump to first / last visible node
`Enter` / `Space`	Activate the focused node (toggles expand/collapse on a branch)
Type a character	Type-ahead to focus the next node starting with that character

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

Element	Token
Font family	`--font-wk-sans`
Text size	`--text-wk-md`
Text color	`--color-wk-text`
Muted text (chevron)	`--color-wk-text-muted`
Hover background	`--color-wk-bg-muted`
Focus ring	`--color-wk-ring` / `--ring-wk-width`
Node padding	`--padding-wk-x-sm` / `--padding-wk-y-sm`
Border radius	`--radius-wk-sm`
Transition	`--transition-wk-duration`

Customization

Override defaults in config/wirekit.php:

'components' => [
    'tree-view' => [],
],