Tree

InstallationCopy Anchor Link

npx vayu-ui-cli@latest add tree

UsageCopy Anchor Link

AnatomyCopy Anchor Link

import { Tree } from 'vayu-ui';
import type { TreeNode } from 'vayu-ui';

const data: TreeNode[] = [
  { id: 'root', label: 'Root', children: [{ id: 'child', label: 'Child' }] },
];

<Tree data={data} aria-label="My tree">
  <Tree.Search searchQuery={query} onSearchChange={setQuery} />
  <Tree.Actions onExpandAll={handleExpandAll} onCollapseAll={handleCollapseAll} />
  <Tree.Container>
    <Tree.Nodes nodes={data} />
  </Tree.Container>
</Tree>;

• Tree — Root provider that manages expand, select, and check state. Wraps all sub-components.
• Tree.Search — Controlled search input for filtering nodes. Requires searchQuery and onSearchChange.
• Tree.Actions — Toolbar with Expand All and Collapse All buttons.
• Tree.Container — Bordered container with a built-in empty state fallback.
• Tree.Nodes — Renders an array of TreeNode objects. Typically receives the filtered data array.
• Tree.Node — Renders a single node with optional children. Used internally by Tree.Nodes or manually for custom layouts.

AccessibilityCopy Anchor Link

• Keyboard Support:
  • ArrowDown — Move focus to the next visible node.
  • ArrowUp — Move focus to the previous visible node.
  • ArrowRight — Expand a collapsed node, or move focus to the first child of an expanded node.
  • ArrowLeft — Collapse an expanded node, or move focus to the parent of a collapsed node.
  • Home — Move focus to the first visible node.
  • End — Move focus to the last visible node.
  • Enter — Toggle expand/collapse on parent nodes, select in normal mode, or toggle checkbox in checkbox mode.
  • Space — Select a node in normal mode, or toggle checkbox in checkbox mode.
• ARIA Attributes:
  • Root has role="tree" with aria-label or aria-labelledby.
  • aria-multiselectable is set to true when mode="checkbox".
  • Each node has role="treeitem" with aria-expanded, aria-selected, aria-disabled, and aria-level.
  • Child groups use role="group" with aria-label describing the parent.
  • Checkboxes use role="checkbox" with aria-checked (true, false, or "mixed" for indeterminate).
  • Search input uses role="searchbox" with aria-label="Search tree".
  • Action buttons use role="toolbar" with aria-label="Tree actions".
• Focus Behavior:
  • Only the focused node has tabIndex={0}; all others have tabIndex={-1}.
  • Focus ring is shown via ring-2 ring-inset ring-focus.
  • Arrow key navigation cycles through visible nodes only, skipping collapsed children.

Screen reader behaviorCopy Anchor Link

When a user navigates to a tree node, the screen reader announces the node label, its nesting level (via aria-level), and its expanded or collapsed state (via aria-expanded). In checkbox mode, the checked state is announced as checked, unchecked, or indeterminate (via aria-checked). When a node is expanded or collapsed, the screen reader announces the state change. Parent nodes are announced with their child count via the role="group" container. Disabled nodes are announced as disabled (via aria-disabled). Users can navigate between nodes using arrow keys, and the screen reader announces each node as it receives focus. The search input is announced as a search box, and toolbar buttons are announced with their respective labels.

Component Folder StructureCopy Anchor Link

Tree/
├── Tree.tsx            # Root component with context provider and state management
├── TreeNode.tsx        # Individual node rendering with expand, select, and checkbox
├── TreeContainer.tsx   # Bordered container with empty state fallback
├── TreeActions.tsx     # Expand All / Collapse All toolbar
├── TreeSearch.tsx      # Controlled search input with clear button
├── hooks.ts            # useTree hook for accessing tree context
├── utils.ts            # Tree traversal utilities (flatten, find, filter)
├── types.ts            # TypeScript type definitions
└── index.ts            # Re-exports all components, hook, and types

PropsCopy Anchor Link

Tree (Root)Copy Anchor Link

Tree.SearchCopy Anchor Link

Tree.ActionsCopy Anchor Link

Tree.ContainerCopy Anchor Link

Tree.NodesCopy Anchor Link

Tree.NodeCopy Anchor Link

TreeNode (Data Type)Copy Anchor Link