Tree

Example

<ul role="tree" aria-label="Project files" data-slean="tree" data-slean-value="button">
	<li role="treeitem" aria-expanded="true" aria-selected="false" data-slean-value="src" tabindex="-1">
		<span data-slean-part="label">src</span>
		<ul role="group">
			<li role="treeitem" aria-expanded="true" aria-selected="false" data-slean-value="primitives" tabindex="-1">
				<span data-slean-part="label">primitives</span>
				<ul role="group">
					<li role="treeitem" aria-selected="true" data-slean-value="button" tabindex="0">
						<span data-slean-part="label">button.ts</span>
					</li>
					<li role="treeitem" aria-selected="false" data-slean-value="tabs" tabindex="-1">
						<span data-slean-part="label">tabs.ts</span>
					</li>
				</ul>
			</li>
			<li role="treeitem" aria-expanded="false" aria-selected="false" data-slean-value="styles" tabindex="-1">
				<span data-slean-part="label">styles</span>
				<ul role="group">…</ul>
			</li>
		</ul>
	</li>
	<li role="treeitem" aria-selected="false" data-slean-value="readme" tabindex="-1">
		<span data-slean-part="label">README.md</span>
	</li>
</ul>

<script lang="ts">
	// With @svelte-lean/vite the register import is injected for the static data-slean="tree".
	import '@svelte-lean/styles/tree.css';
	import type { TreeChangeDetail } from '@svelte-lean/primitives/tree';
	import { on } from 'svelte/events';

	interface Node {
		value: string;
		label: string;
		open?: boolean;
		children?: Node[];
	}

	let { nodes, selected = $bindable('') }: { nodes: Node[]; selected?: string } = $props();
	// The first item is the tab stop until the behavior moves it.
	const first = nodes[0]?.value;
</script>

{#snippet items(list: Node[])}
	{#each list as node (node.value)}
		<li
			role="treeitem"
			data-slean-value={node.value}
			aria-expanded={node.children ? (node.open ?? false) : undefined}
			aria-selected={node.value === selected}
			tabindex={node.value === (selected || first) ? 0 : -1}
		>
			<span data-slean-part="label">{node.label}</span>
			{#if node.children}<ul role="group">{@render items(node.children)}</ul>{/if}
		</li>
	{/each}
{/snippet}

<ul
	role="tree"
	aria-label="Project files"
	data-slean="tree"
	data-slean-value={selected}
	{@attach (node) =>
		on(node, 'slean:change', (event) => {
			selected = (event as CustomEvent<TreeChangeDetail>).detail.value;
		})}
>
	{@render items(nodes)}
</ul>

Why this implementation exists

The platform’s disclosure (<details>) opens and closes a section, but a tree is more: the whole hierarchy is one tab stop, the arrows move through the visible items, Right and Left open, close and move between levels, and typing jumps to an item. None of that is native.

All of it can live in the DOM. aria-expanded is the expansion and the stylesheet hides a collapsed group, aria-selected and the root’s data-slean-value are the selection, and one item holds tabindex="0". The behavior computes the visible items from the attributes when a key is pressed and keeps nothing in between.

Usage

Install @svelte-lean/primitives for the behavior and @svelte-lean/styles for the stylesheet. With @svelte-lean/vite the registration is injected for every static data-slean="tree"; without it, import the register module once.

npm install @svelte-lean/primitives

pnpm add @svelte-lean/primitives

yarn add @svelte-lean/primitives

bun add @svelte-lean/primitives

import '@svelte-lean/primitives/tree/register';

import '@svelte-lean/styles/tree.css';

Render nested lists: role="tree" on the root, role="treeitem" on each item with a label part as its first child, aria-expanded and a role="group" list on parents. Give exactly one item tabindex="0".

Listen to slean:change for the selected value and slean:toggle for expansion. Set data-slean-selection="none" for a navigation tree whose labels are links.

Anatomy

Runtime profile

The tree registers one click and one keydown handler with the shared router. A thousand trees keep one listener per type (tests/tree.test.ts).

Accessibility contract

• role="tree" named by aria-label; treeitem, group, aria-expanded and aria-selected. Assistive technology derives the level and the position from the nesting.
• One tab stop; the arrows, Home, End, * and typeahead move focus among the visible items.
• Closing a parent that holds focus moves focus to the parent, so focus never disappears into a hidden group.
• The focus ring and the selection are drawn on the label, not around the whole subtree.

Keyboard

Platform features

Without JavaScript

The tree renders as nested lists with the server's expansion. Collapsed groups stay hidden and cannot be opened; links in labels still work. Where a hierarchy must be browsable without JavaScript, use nested disclosures.

Server rendering

Render aria-expanded, aria-selected and the roving tabindex on the server. The behavior writes nothing until the first interaction.

Before hydration

Before the behavior loads, clicks do nothing and Tab reaches the one item with tabindex 0. The first event after hydration works on the server's markup.

Styling

tree.css indents children under a guide line, draws the chevron of a parent with two borders (turned by aria-expanded, mirrored under :dir(rtl)), hides collapsed groups and puts the focus ring and the selection on the label. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: :dir(rtl), :focus-visible, :hover, [aria-disabled="true"], [aria-expanded="false"], [aria-expanded="true"], [aria-expanded], [aria-selected="true"], [role="group"], [role="treeitem"].

Compatibility notes

Nothing beyond lists and ARIA tree roles. Multiple selection, checkboxes and drag and drop are not part of the primitive.

Examples

Children loaded on demand

slean:toggle is dispatched before a parent opens or closes, with the item’s value and the new state. A listener that fills the group the first time a parent opens loads a large hierarchy one level at a time; cancelling the event keeps the item as it is.

<script lang="ts">
	import type { TreeToggleDetail } from '@svelte-lean/primitives/tree';
	import { on } from 'svelte/events';

	// Children per parent value, filled the first time a parent opens.
	let children = $state<Record<string, { value: string; label: string }[]>>({});

	function toggle(event: Event) {
		const { value, expanded } = (event as CustomEvent<TreeToggleDetail>).detail;
		if (expanded && !children[value]) {
			children[value] = []; // an empty group while the request runs
			fetch(`/api/folders/${value}`)
				.then((response) => response.json())
				.then((list) => (children[value] = list));
		}
	}
</script>

<ul role="tree" aria-label="Folders" data-slean="tree" {@attach (node) => on(node, 'slean:toggle', toggle)}>
	…
</ul>

Testing

• packages/primitives/tests/tree.test.ts Vitest: keyboard, RTL, typeahead, clicks, cancelable events, nested trees, 1000 roots
• apps/playground/tests/primitives/widgets.spec.ts Playwright: tooltip, toast, tree, range slider and number field in Chrome, with axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

• packages/primitives/src/tree/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/tree/contract.ts typed constants: name, tier, base, parts, options, events
• packages/primitives/src/tree/behavior.ts the behavior definition
• packages/primitives/src/tree/register.ts the registration module
• packages/styles/css/tree.css the optional stylesheet