# Tree
Browse a hierarchy of files, pages, or choices with expandable branches.
Use a Tree when items have children, like files in folders or pages in a docs sidebar. Start with nested parts, then add selection, checkboxes, or children loaded from a server as you need them.
```ts title="demo.ts"
import "@ui-sdk/web/tree"
import {
ChevronRight,
createElement,
File,
Folder,
FolderOpen,
type IconNode,
} from "lucide"
type Node = { value: string; label: string; children?: Node[] }
const files: Node[] = [
{
value: "app",
label: "app",
children: [
{ value: "app/layout.tsx", label: "layout.tsx" },
{ value: "app/page.tsx", label: "page.tsx" },
{
value: "app/settings",
label: "settings",
children: [{ value: "app/settings/page.tsx", label: "page.tsx" }],
},
],
},
{
value: "components",
label: "components",
children: [
{ value: "components/button.tsx", label: "button.tsx" },
{ value: "components/card.tsx", label: "card.tsx" },
],
},
{ value: "components.json", label: "components.json" },
{ value: "package.json", label: "package.json" },
{ value: "README.md", label: "README.md" },
]
const icon = (node: IconNode) =>
createElement(node, { "aria-hidden": "true" }).outerHTML
function markup(items: Node[]) {
let html = ""
for (const item of items) {
html += `
${
item.children
? `${icon(ChevronRight)}
${icon(Folder)}
${icon(FolderOpen)}`
: icon(File)
}
${item.label}
${item.children ? `${markup(item.children)}` : ""}
`
}
return html
}
function mount(root: HTMLElement) {
root.innerHTML = `
${markup(files)}
`
}
export { mount }
```
Expand components to see its files. Use the arrow keys to move between rows and open or close branches.
## Installation
```bash
npm install @ui-sdk/web @ui-sdk/core
```
Importing the component defines its elements. On the server the import does nothing.
```ts
import "@ui-sdk/web/tree"
```
## Composition
Use the following composition to build a `ui-tree`:
```text
ui-tree
├── ui-tree-item
│ ├── ui-tree-item-label
│ │ └── ui-tree-item-indicator
│ └── ui-tree-group
│ └── ui-tree-item
│ └── ui-tree-item-label
└── ui-tree-item
└── ui-tree-item-label
```
Give the tree an accessible name and every item a unique `value`. An item with a `ui-tree-group` inside it is a branch. The group holds its children; the label names the item. The indicator and checkbox are optional, and they belong to the item around them, so put them inside its label to make them part of the row.
## Usage
Import the parts and put them together:
```html
›
src
index.tspackage.json
```
## Items as Data
Pass `items` to give the tree its full hierarchy, including collapsed branches. Each `TreeItemData` has a `value`, a `label`, and optional `children`. With no `ui-tree-item` elements of its own, the tree renders bare parts from the data:
```ts
const items: TreeItemData[] = [
{
value: "fruit",
label: "Fruit",
children: [
{ value: "apple", label: "Apple" },
{ value: "banana", label: "Banana" },
],
},
{ value: "bread", label: "Bread" },
]
const tree = document.querySelector('ui-tree[aria-label="Groceries"]')!
tree.items = items
```
To render the rows yourself, keep `items` on the tree and write them with a recursive function, so keyboard navigation, item counts, and the element's `api` still know the whole hierarchy:
```ts
function markup(items: TreeItemData[]) {
let html = ""
for (const item of items)
html += `
${item.label}
${item.children ? `${markup(item.children)}` : ""}
`
return html
}
const tree = document.querySelector('ui-tree[aria-label="Groceries"]')!
tree.innerHTML = markup(items)
tree.items = items
```
## File Paths
Pass `paths` for a file explorer. Folders become branches and sort before files; a path ending in `/` represents an empty folder. `treeFromPaths()` returns the same data when you want to render the rows yourself.
Selection and activation are separate. This example uses `activation="automatic"` so arrow keys select a file, then the `action` event opens it. Pass a promise to the event's `detail.waitUntil()` to show a pending state while it opens.
```ts title="paths.ts"
import { treeFromPaths, type TreeItemData } from "@ui-sdk/core/tree"
import "@ui-sdk/web/tree"
import { ChevronRight, createElement, LoaderCircle } from "lucide"
import { log } from "./log"
const paths = [
"src/index.ts",
"src/lib/format.ts",
"src/lib/parse.ts",
"src/routes/home.tsx",
"src/routes/about.tsx",
"tests/",
"package.json",
"tsconfig.json",
]
const items = treeFromPaths(paths)
const files = new Set(paths.filter((path) => !path.endsWith("/")))
function markup(items: TreeItemData[]) {
let html = ""
for (const item of items) {
html += `
${
item.children
? `${createElement(ChevronRight, { "aria-hidden": "true" }).outerHTML}`
: ""
}
${item.label}
${createElement(LoaderCircle, { "aria-hidden": "true", "data-show": "pending" }).outerHTML}
${item.children ? `${markup(item.children)}` : ""}
`
}
return html
}
function mount(root: HTMLElement) {
root.innerHTML = `
${markup(items)}
`
const tree = root.querySelector("ui-tree")!
tree.paths = paths
tree.addEventListener("action", (event) => {
const { value, waitUntil } = event.detail
if (!files.has(value)) {
return
}
waitUntil(
new Promise((resolve) => setTimeout(resolve, 600)).then(() =>
log(root, `Opened ${value}`)
)
)
})
}
export { mount }
```
Arrow down to package.json, then press Enter. It shows a spinner while it opens, then the console logs Opened package.json.
## Selection
The default `mode="single"` uses one string value or `null`. Use `"multiple"` for an array, or `"none"` when items should only navigate or perform actions.
`activation="automatic"` selects while arrow keys move in single selection mode. Pressing a branch also expands or collapses it; set `expand-on-press` to `false` to leave expansion to the indicator and arrow keys.
## Multiple Selection
`mode="multiple"` makes the value an array. Cmd-click or Ctrl-click toggles one item, Shift extends a range, and Cmd+A or Ctrl+A selects the visible items. This example sets `expand-on-press` to `false`, so clicking Inbox or Projects selects the folder without closing it.
```ts title="multiple.ts"
import type { TreeItemData } from "@ui-sdk/core/tree"
import "@ui-sdk/web/tree"
import { ChevronRight, createElement } from "lucide"
import { log } from "./log"
const items: TreeItemData[] = [
{
value: "inbox",
label: "Inbox",
children: [
{ value: "updates", label: "Updates" },
{ value: "forums", label: "Forums" },
{ value: "promotions", label: "Promotions" },
],
},
{
value: "projects",
label: "Projects",
children: [
{ value: "website", label: "Website" },
{ value: "mobile", label: "Mobile app" },
],
},
{ value: "archive", label: "Archive" },
{ value: "trash", label: "Trash" },
]
function markup(items: TreeItemData[]) {
let html = ""
for (const item of items) {
html += `
${
item.children
? `${createElement(ChevronRight, { "aria-hidden": "true" }).outerHTML}`
: ""
}
${item.label}
${item.children ? `${markup(item.children)}` : ""}
`
}
return html
}
function mount(root: HTMLElement) {
root.innerHTML = `
${markup(items)}
`
const tree = root.querySelector("ui-tree")!
tree.items = items
tree.addEventListener("valuechange", (event) => {
const value = event.detail.value as string[]
log(root, `${value.length} selected: ${value.join(", ")}`)
})
}
export { mount }
```
Cmd-click or Ctrl-click Archive to add it to the selection. Shift-click or Shift+Arrow extends a range, and the console logs what's selected.
## Checkboxes
Add `checkable` and `ui-tree-item-checkbox` for a checked state separate from selection. Space checks the focused item. Checking a branch checks its descendants, and a partly checked branch reports a mixed state.
`check-strategy` chooses what the `checked` array reports:
| Strategy | Reported Values |
| --------------- | ---------------------------------------- |
| `"leaf"` | Checked leaves. This is the default. |
| `"trunk"` | The outermost fully checked items. |
| `"branch"` | Every fully checked item. |
| `"independent"` | Each item on its own, without cascading. |
```ts title="checkboxes.ts"
import type { TreeItemData } from "@ui-sdk/core/tree"
import "@ui-sdk/web/tree"
import { ChevronRight, createElement } from "lucide"
import { log } from "./log"
const items: TreeItemData[] = [
{
value: "frontend",
label: "Frontend",
children: [
{ value: "react", label: "React" },
{ value: "vue", label: "Vue" },
{ value: "svelte", label: "Svelte" },
],
},
{
value: "backend",
label: "Backend",
children: [
{ value: "node", label: "Node" },
{
value: "databases",
label: "Databases",
children: [
{ value: "postgres", label: "Postgres" },
{ value: "sqlite", label: "SQLite" },
],
},
],
},
]
function markup(items: TreeItemData[]) {
let html = ""
for (const item of items) {
html += `
${
item.children
? `${createElement(ChevronRight, { "aria-hidden": "true" }).outerHTML}`
: ""
}
${item.label}
${item.children ? `${markup(item.children)}` : ""}
`
}
return html
}
function mount(root: HTMLElement) {
root.innerHTML = `
${markup(items)}
`
const tree = root.querySelector("ui-tree")!
tree.items = items
tree.addEventListener("checkedchange", (event) => {
log(root, `Checked ${event.detail.value.join(", ") || "nothing"}`)
})
}
export { mount }
```
Press Space on Vue, then on Frontend. Frontend is mixed while only some of its items are checked, and the console logs the trunk strategy's values.
## Links
Set `mode="none"` for a navigation tree, then bind each label to a link with `as-child`. `current` identifies the current page with `aria-current="page"`, expands its ancestors, and gives it the initial Tab stop. Update it when your route changes.
```ts title="links.ts"
import type { TreeItemData } from "@ui-sdk/core/tree"
import "@ui-sdk/web/tree"
import { ChevronRight, createElement } from "lucide"
const pages: TreeItemData[] = [
{
value: "getting-started",
label: "Getting started",
children: [
{ value: "introduction", label: "Introduction", href: "#introduction" },
{ value: "installation", label: "Installation", href: "#installation" },
],
},
{
value: "components",
label: "Components",
children: [
{ value: "accordion", label: "Accordion", href: "#accordion" },
{ value: "dialog", label: "Dialog", href: "#dialog" },
{ value: "tree", label: "Tree", href: "#tree" },
],
},
{ value: "changelog", label: "Changelog", href: "#changelog" },
]
const links = new Set(
pages
.flatMap((page) => [page, ...(page.children ?? [])])
.filter((page) => page.href)
.map((page) => page.value)
)
function markup(items: TreeItemData[]) {
let html = ""
for (const item of items) {
const content = `
${
item.children
? `${createElement(ChevronRight, { "aria-hidden": "true" }).outerHTML}`
: ""
}
${item.label}`
html += `
${
item.href
? `${content}`
: `${content}`
}
${item.children ? `${markup(item.children)}` : ""}
`
}
return html
}
function mount(root: HTMLElement) {
root.innerHTML = `
${markup(pages)}
`
const tree = root.querySelector("ui-tree")!
tree.items = pages
tree.addEventListener("action", (event) => {
const { value, event: trigger } = event.detail
if (!links.has(value)) {
return
}
trigger?.preventDefault()
tree.setAttribute("current", value)
})
}
export { mount }
```
Choose Dialog. The current-page marker moves to it, and you stay on this docs page.
## Disabled
Disabled items can't be selected, checked, expanded, or run. They stay focusable so screen readers can find them. Set `focusable-when-disabled` to `false` to skip them, or `disabled` on the root to disable the whole tree. A disabled `