TreeView

A keyboard-navigable tree for nested folders and structured content, with file-type icons and animated expand/collapse.

When to use

• File browsers, document outlines, nested categories or settings sections.
• When depth matters and people need to open several branches at once.
• Use Accordion for a single level of collapsible sections, and JsonViewer for raw JSON data.

Usage

import { TreeView } from "@/components/iris/tree-view/tree-view";

h(TreeView, {
  "aria-label": "notdocs repository",
  defaultExpandedIds: ["docs"],
  onSelect: (node) => openFile(node.id),
  nodes: [
    {
      id: "docs",
      label: "docs",
      children: [
        { id: "docs/roadmap.md", label: "roadmap.md" },
        { id: "docs/seat-based-pricing.md", label: "seat-based-pricing.md" },
      ],
    },
    { id: "CHANGELOG.md", label: "CHANGELOG.md" },
  ],
});

Props

Prop	Type	Default	Description
nodes	TreeNode[]	— (required)	{ id: string; label: string; children?: TreeNode[]; icon?: ReactNode }. Nodes with children are folders.
defaultExpandedIds	string[]	[]	Folders open on first render (uncontrolled).
expandedIds	string[]	—	Controlled open folders; pair with onExpandedChange.
onExpandedChange	(ids: string[]) => void	—	Called when a folder opens or closes.
onSelect	(node: TreeNode) => void	—	Called when a row is clicked or activated with Enter/Space (folders also toggle).
aria-label	string	"File tree"	Accessible name of the tree.

Notes

• Follows the WAI-ARIA tree pattern (role="tree" / treeitem): Up/Down move, Right opens or enters a folder, Left closes or goes to the parent, Home/End jump, Enter or Space selects (and toggles a folder).
• Without a custom icon, folders get an open/closed folder glyph and files a document glyph tinted by extension (.ts/.tsx, .css, .md, .json).
• Rows enter and leave with a short fade and height collapse; instant under reduced motion.
• Reads the theme colours surface, hover, line, ink, ink-2 and ink-3; file tints are mixed toward ink so they hold in both themes.