Tree

A headless hierarchical collection primitive with keyboard navigation, expansion state, row selection, and section labels.

Anatomy

Tree.Item declares every node and Tree.Children marks the nested subtree explicitly — its presence is what makes a parent expandible. Interactive parts (Tree.Trigger, Tree.Checkbox, Tree.Label) go directly inside the item. Rows indent automatically through the --tree-indent-size CSS variable.

<script>
	import { Tree } from '@human-kit/ui';
</script>

<Tree.Root aria-label="Files" selectionMode="multiple">
	<Tree.Section aria-label="Primary files">
		<Tree.Header>Files</Tree.Header>
		<Tree.Item id="documents" title="Documents">
			<Tree.Trigger aria-label="Toggle Documents">▶</Tree.Trigger>
			<Tree.Checkbox aria-label="Select Documents" />
			<Tree.Label>Documents</Tree.Label>
			<Tree.Children>
				<Tree.Item id="reports" title="Reports">
					<Tree.Label>Reports</Tree.Label>
				</Tree.Item>
			</Tree.Children>
		</Tree.Item>
	</Tree.Section>
</Tree.Root>

Checkbox selection

With selectionMode="multiple", Tree.Checkbox and Tree.CheckboxIndicator give each row an explicit selection affordance. selectionPropagation="descendants" propagates selection through a subtree, marking partially selected ancestors as indeterminate; the default "none" keeps selection flat, so ancestors stay unchecked unless explicitly selected.

Sections and headers

Tree.Section groups related top-level items and Tree.Header labels the group. When a section does not render a header, provide aria-label on the section instead.

Usage guidelines

• Use Tree.Root as the stateful container for focus, expansion, selection, and actions, and give it aria-label or aria-labelledby.
• Use expandedKeys / onExpandedKeysChange for controlled expansion and defaultExpandedKeys for uncontrolled initial expansion.
• Use selectedKeys / onSelectionChange for controlled selection and defaultSelectedKeys for uncontrolled initial selection.
• Use selectionPropagation="none" for flat selection where ancestors stay unchecked unless explicitly selected, or selectionPropagation="descendants" to propagate selection through a subtree.
• Use Tree.Item for every node, regardless of whether it is currently a branch or a leaf, and place nested descendants inside Tree.Children.
• Use Tree.Trigger for explicit branch expansion affordances and Tree.Checkbox / Tree.CheckboxIndicator for explicit selection affordances.
• Tree.Item is the real treeitem surface: focus, hover, selection, and pressed states are exposed on the item itself.
• Collapsed descendants are omitted from the rendered tree DOM while their structural state remains in the internal collection.

Accessibility

• Tree.Root renders role="tree" and each Tree.Item renders as a flattened role="treeitem" row.
• Tree.Section renders role="group" when top-level items need a labeled section.
• Keyboard support includes ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, Space, Enter, and typeahead.
• ArrowLeft and ArrowRight are the primary expansion keys. Enter only toggles expansion when selection is disabled and no onAction handler is present.
• Focus stays on the item row; Tree.Trigger is clickable but is not part of arrow-key navigation.
• disabledBehavior="selection" keeps items focusable and actionable while blocking selection; disabledBehavior="all" makes disabled items fully non-interactive.

API reference

Root

The stateful tree container. Renders role="tree" and manages focus, expansion, selection, and actions for all items.

* required. Native HTML attributes of the underlying element are also accepted.

Section

Groups related top-level items under an optional header. Renders role="group".

* required. Native HTML attributes of the underlying element are also accepted.

Header

A visual label for a section's items.

* required. Native HTML attributes of the underlying element are also accepted.

Item

A single tree node. Renders the flattened role="treeitem" row and exposes focus, hover, selection, and pressed state on it.

* required. Native HTML attributes of the underlying element are also accepted.

Children

Marks the nested subtree of an item. Its presence makes the parent expandible on first render and during SSR.

* required. Native HTML attributes of the underlying element are also accepted.

Label

The text label of an item row; also labels the row for assistive technology.

* required. Native HTML attributes of the underlying element are also accepted.

Trigger

An explicit expand/collapse button for a branch. Only rendered when the item has children, and not part of arrow-key navigation.

* required. Native HTML attributes of the underlying element are also accepted.

Checkbox

An explicit selection affordance for an item row, kept in sync with the tree selection (including indeterminate ancestors).

* required. Native HTML attributes of the underlying element are also accepted.

CheckboxIndicator

The visual mark inside a tree checkbox. Mounted while the checkbox is checked or indeterminate.

* required. Native HTML attributes of the underlying element are also accepted.