---
name: tree-view-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit TreeView for
hierarchical data with Zag.js tree-view behavior, node collection, branch and
item parts, selection behavior, icons, indentation, expansion, selection, and
keyboard/typeahead support.
metadata:
component_version: "1.3.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux zag-compound-components app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: "https://zagjs.com/components/react/tree-view"
contributor_sources: "libs/ui/src/molecules/tree-view.tsx libs/ui/src/tokens/components/molecules/_tree-view.css libs/ui/stories/molecules/tree-view.stories.tsx libs/ui/src/molecules/tree-view.figma.ts"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit TreeView Usage
Use TreeView for hierarchical navigation or selection. Do not flatten trees
into custom nested lists when keyboard navigation/selection matters.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `TreeView`.
**Use it when**
- Selecting or managing items in a hierarchy with keyboard tree semantics: folders, category trees in admin, file browsers.
**Use something else when**
| Need | Use instead |
| --- | --- |
| Site/category navigation links | VerticalNavigation |
| A hierarchical form value | CascadeSelect |
| Flat lists | Table / list |
**Do**
- Show counts or state per node where helpful; keep labels short.
- Persist expanded state across navigation.
- Offer search/filter for large trees.
**Don't**
- Put complex forms inside nodes.
- Nest deeper than ~5 levels without breadcrumbs or search.
**Copy and states**
- Node labels are names; actions on nodes follow Menu rules.
**Behaviour (from the UX spec)**
- Expansion, focus and selection are separate: opening a branch never selects, navigates or changes data.
- Same-named nodes in different branches need path context in the label or a description.
- Loading children that fails or returns empty must not create or keep a selection of a phantom node.
- `TreeView.IndentGuide` and `TreeView.NodeIcon` are supplements; hierarchy must read from names and indentation.
**Figma → code**
| Figma | Code |
| --- | --- |
| `size=sm…lg` | same prop |
| `state=selected` | `selectedValue` / `defaultSelectedValue` |
| `state=disabled` | `disabled` on the node data (inherited by the subtree) |
| branch indicator `open` / `closed` | `expandedValue` / `defaultExpandedValue` |
| nodeicon / indentguide | `TreeView.NodeIcon` / `TreeView.IndentGuide` (`showNodeIcons`, `showIndentGuides` on `TreeView.Node`) |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/TreeView → UX guidelines*.
## Setup
```tsx