Tree
newFolders inside folders inside folders. A tree to browse, select or check nested items, with lazy folders and room for ten thousand nodes.
No file open
Open Props in the corner of the example to try variant, size and disabled. ghost, the default, draws no frame: trees mostly live in sidebars and cards that have one; outline draws a frame like Listbox's. A disabled node can't be selected, and the arrow keys skip it; a disabled tree dims every row and leaves the tab order.
size runs from xs to xl. Rows are 28, 32, 36, 40 and 48px tall, as tall as a Listbox option or a Menu item of the same size. Each level indents by an icon and a gap, so a child's chevron sits under its parent's icon.
Installation
Usage
<script setup lang="ts">
import { Tree, TreeItem, TreeItemLabel, TreeItemToggle } from '@/components/ui/tree'
const files = [
{
id: 'src',
label: 'src',
children: [
{ id: 'src/App.vue', label: 'App.vue' },
{ id: 'src/main.ts', label: 'main.ts' },
],
},
{ id: 'package.json', label: 'package.json' },
]
const opened = shallowRef()
</script>
<template>
<Tree v-slot="{ items }" v-model="opened" :items="files" aria-label="Files">
<TreeItem v-for="row in items" :key="row._id" :item="row">
<TreeItemToggle />
<TreeItemLabel>{{ row.value.label }}</TreeItemLabel>
</TreeItem>
</Tree>
</template>
Pass the nodes as items. Tree flattens what's open into items, and you draw each one as a TreeItem: a TreeItemToggle for the chevron, a TreeItemIcon, a TreeItemLabel, or anything else. The row's state (expanded, selected, checked, level and more) comes with its slot. A node with children is a folder; children: [] is a folder that is empty or not loaded yet. disabled, loading and defaultExpanded do what they say.
v-model holds the node you passed in, not a copy, so opened === files[1] holds. v-model:expanded holds the keys of the open nodes.
Width classes and aria-label go straight on Tree. Or put it in a Field.
For trees of plain data, DataTree draws these rows itself, adds loading, empty and error states and virtualizes with one prop.
Examples
Multiple
With multiple, v-model is an array. Each click adds or removes a node by default. With selection-behavior="replace", it works like a file manager: a click picks one node, Ctrl or ⌘-click adds to it, and Shift-click or Shift + arrows select a range.
0 selected. Click to pick one, Ctrl or ⌘-click to add, Shift-click or Shift + arrows for a range.
Checkboxes
checkbox is checkbox mode: rows use aria-checked, and a TreeItemCheckbox in each row shows the state. A click checks only on the checkbox; on the rest of the row it opens or closes the folder, and Space checks from the keyboard. Checking a folder checks everything under it, and a folder shows checked, unchecked or indeterminate from what's inside. Disabled nodes keep their state, so the locked permission below stays off whatever its folder does.
v-model holds every checked node, folders that are fully checked included. A list of the checked leaves is one filter away. Echo a model back with only the leaves, or only a folder, and the tree reads it the same.
Add multiple too, so v-model is typed as an array. :cascade="false" checks nodes one by one.
projects.read
Form
In a required field the tree gets aria-required. When the field is invalid, it gets aria-invalid and --destructive checkboxes, plus a --destructive frame with outline. Most forms want keys, not nodes: map them in a computed. Here vee-validate and zod check that something is granted. Press Save without checking anything.
Posting a plain form? name adds a hidden input per selected key. Add required too, and the form won't submit with nothing selected; the tree takes focus instead.
Select without expanding
By default a click both selects a row and opens it, and a click on the chevron only opens it. With :toggle-on-click="false", a click only selects; the chevron or a double click opens the folder. Arrow keys work the same either way.
Showing Inbox. Click the chevron or double-click a folder to open it.
Loading children
Give an unloaded folder children: []: it gets a chevron and aria-expanded. Fetch in @update:expanded, set loading: true on the node meanwhile for a spinner and aria-busy, then replace the node with its children.
Expand, collapse and reveal
The tree exposes expandAll(), collapseAll() and scrollToKey(key). To reveal a node, say the page the router is on, add getAncestorKeys(items, key) to v-model:expanded. Selecting a hidden node works without it.
Filtering
Filter items yourself: keep the matches and the folders leading to them, and open those folders. The tree only renders what it gets.
Custom rows
A row is whatever you put in TreeItem. Its slot gets the node and its state, so the icon can follow expanded and a status can follow the node.
Keep buttons out of rows: a row is one focusable item, so the keyboard can't reach a button inside it. Put actions in a context menu.
Composition
Rows hold any content: an Avatar, two lines of text, a badge.
Context menu
Put a Menu with context-menu around the tree and find the row from the contextmenu event's target: rows carry data-key. Shift+F10 and the context menu key open it on the focused row. A field inside a row keeps its keys, and @click.stop keeps a click in it from selecting the row.
Virtualization
Put a TreeVirtualizer in the tree instead of the rows, and only the rows near the view are rendered: it hands you one item at a time. The tree scrolls itself, so make it a div (as="div") and give it a height; it warns in development when it has none. Rows get a fixed height, read from --tree-item-height. Typeahead can only match rows in the page, so text-content tells it each node's text, its label by default.
10,100 nodes, about 20 rendered. Try End, or type a name.
Known limits
Tree is built on Reka UI's, which is still alpha. Kappa keeps the selection itself, which works around a few of its issues. These remain:
- No open and close animation: rows render as a flat list, so there's no subtree to animate (reka-ui#1561). New rows fade in.
- A virtualized tree has rows of one fixed height (reka-ui#1266), and it has to be the scroller, so it can't sit in a ScrollArea. With
outline, the edge fade masks the frame too: put a ghost tree in a framed box, as above. getChildrencan't be async (reka-ui#1379); load children as shown above.- No
role="treegrid"(reka-ui#1866). For a tree with columns, use DataTable's expanding rows. - No drag and drop.
- A disabled folder can't be opened by the user. Open it with
v-model:expanded. - Row clicks don't reach click listeners above the tree. Use
@select, orcontextmenufor menus. - Typeahead matches a row's whole text, everything after the label included. In a virtualized tree it matches
TreeVirtualizer'stext-content. - Enter, and outside a virtualized tree the arrow keys, Home, End, PageUp and PageDown, stop at the row, so a
@keydownlistener on the tree doesn't hear them. That's what keeps typeahead working right after them. Escape and Tab go through. - Arrow keys don't wrap from the last row to the first. Reka UI 2.11 adds
loop, but the tree supports 2.10 too.
API Reference
Every part accepts class, merged over its base classes.
Tree
| Prop | Default | Type and description |
|---|---|---|
| items* | — | T[]The top-level nodes. A node's |
| modelValue | undefined | Model | nullThe selected node, or an array of them with |
| defaultValue | undefined | ModelThe starting selection when |
| multiple | — | MLets more than one node be selected; |
| expanded | — | string[]The keys of the expanded nodes, bound with |
| defaultExpanded | — | string[]The starting expanded keys when |
| selectionBehavior | "toggle" | "toggle" | "replace"
|
| checkbox | — | booleanCheckbox mode. Rows use |
| cascade | undefined | booleanChecking a parent checks every enabled node under it, and a parent counts as checked while all its children are, indeterminate while some are. On by default with |
| getKey | — | ((item: T) => string)Returns a node's unique key, a string. By default |
| getChildren | — | ((item: T) => T[] | undefined)Returns a node's children, |
| toggleOnClick | true | boolean
|
| as | "ul" | stringThe element to render: |
| name | — | stringSubmits the selected keys with their form under this name, one hidden input each. With |
| id | — | stringOverrides the |
| disabled | — | booleanDisables every row. Also set by a disabled field. |
| required | — | booleanMarks the tree required with |
| dir | — | "ltr" | "rtl"Reading direction for Left and Right. |
| variant | — | "ghost" | "outline" | null
|
| size | "md" | TreeSizeSets the height, padding, gap, icons, indent and text of the rows, from |
| Event | Payload and description |
|---|---|
| update:modelValue | [value: Model | undefined]Fires when the selection changes. |
| update:expanded | [value: string[]]Fires when a node expands or collapses, with the expanded keys. Load a folder's children here. |
| select | [event: SelectEvent<T>, item: T]Fires when a row is clicked or chosen with Enter or Space, with the event and the node. Call |
| toggle | [event: ToggleEvent<T>, item: T]Fires before a row expands or collapses from a click or an arrow key, with the event and the node. Call |
| Slot | Scope and description |
|---|---|
| default | { items: FlattenedItem<T>[]; modelValue: Model | null | undefined; expanded: string[]; }The rows, with |
| Member | Type and description |
|---|---|
| expandAll | () => voidExpands every node that has children. |
| collapseAll | () => voidCollapses every node. |
| scrollToKey | (key: string) => booleanScrolls a visible node into view, rendering it first when virtualized, and returns whether it is visible. |
TreeItem
| Prop | Default | Type and description |
|---|---|---|
| item* | — | FlattenedItem<T>One of the flattened rows from the tree's default slot. Key the loop by its |
| disabled | — | booleanDisables the row. A node with |
| as | — | stringThe element to render, |
| Event | Payload and description |
|---|---|
| select | [event: SelectEvent<T>]Fires when the row is clicked or chosen with Enter or Space. Call |
| toggle | [event: ToggleEvent<T>]Fires before the row expands or collapses. Call |
| Slot | Scope and description |
|---|---|
| default | TreeItemSlotProps<T>The row's content, with |
TreeItemToggle
The chevron of a node with children. It is drawn, not a control, so it takes no focus. A click on it opens or closes the node without selecting or checking it.
| Slot | Scope and description |
|---|---|
| default | { expanded: boolean; }The icon of a node with children, with |
TreeItemCheckbox
The row's checkbox in checkbox mode, checked, unchecked or indeterminate. It is drawn, not a control, so it takes no focus; the row carries aria-checked. A click on it checks without expanding.
No props, events, slots or exposed members.
TreeItemIcon
| Slot | Scope and description |
|---|---|
| default | {}An icon before the label, sized by the tree and hidden from screen readers. It turns |
TreeItemLabel
| Slot | Scope and description |
|---|---|
| default | {}The row's text. It takes the free space and truncates with an ellipsis. |
TreeVirtualizer
| Prop | Default | Type and description |
|---|---|---|
| overscan | 12 | numberRows rendered past each edge of the view. |
| estimateSize | undefined | numberRow height in pixels. Measured from |
| textContent | undefined | ((item: T) => string)The text typeahead matches for a node, since only the rows near the view are in the page. The node's |
| Slot | Scope and description |
|---|---|
| default | { item: FlattenedItem<T>; }One row, with |
Props
- items*
T[]The top-level nodes. A node'schildrenare its subtree;[]makes a folder that is empty or not loaded yet. Replace the array, or a node'schildren, to change them.- modelValue
undefined Model | nullThe selected node, or an array of them withmultiple, bound withv-model. The tree emits the nodes you passed in, not copies, and an array in tree order.- defaultValue
undefined ModelThe starting selection whenv-modelis not used.- multiple
MLets more than one node be selected;v-modelis then an array.- expanded
string[]The keys of the expanded nodes, bound withv-model:expanded.- defaultExpanded
string[]The starting expanded keys whenv-model:expandedis not used. Left out, nodes withdefaultExpanded: truestart expanded.- selectionBehavior
"toggle" "toggle" | "replace"toggleadds or removes a node on each click, so clicking the selected node clears it.replacekeeps a node selected; withmultiple, a click replaces the selection, Ctrl or ⌘ adds to it, and Shift or Shift + arrows select a range.- checkbox
booleanCheckbox mode. Rows usearia-checked, andTreeItemCheckboxshows their state; put one in each row. A click checks only on that checkbox, Space anywhere on the row. Turns onmultipleandcascade; addmultipletoo sov-modelis typed as an array.- cascade
undefined booleanChecking a parent checks every enabled node under it, and a parent counts as checked while all its children are, indeterminate while some are. On by default withcheckbox.- getKey
((item: T) => string)Returns a node's unique key, a string. By defaultid, thenvalue, thenlabel. Paths make good keys for files.- getChildren
((item: T) => T[] | undefined)Returns a node's children,undefinedfor a leaf. By defaultchildren.- toggleOnClick
true booleanfalsemakes a click on a row select it only; the chevron or a double click expands it. The keyboard is the same either way.- as
"ul" stringThe element to render:ul, ordivaround aTreeVirtualizer.- name
stringSubmits the selected keys with their form under this name, one hidden input each. Withrequired, the form won't submit while nothing is selected.- id
stringOverrides theidtaken from a surrounding field.- disabled
booleanDisables every row. Also set by a disabled field.- required
booleanMarks the tree required witharia-required, and withnamekeeps a form from submitting while nothing is selected. Also set by a required field.- dir
"ltr" | "rtl"Reading direction for Left and Right.- variant
"ghost" | "outline" | nullghostdraws no frame, for sidebars and cards;outlinedraws a card-like frame, as on Listbox.- size
"md" TreeSizeSets the height, padding, gap, icons, indent and text of the rows, fromxstoxl, after the [control scale](/docs/getting-started/sizing).mdis the default.
Emits
- update:modelValue
[value: Model | undefined]Fires when the selection changes.- update:expanded
[value: string[]]Fires when a node expands or collapses, with the expanded keys. Load a folder's children here.- select
[event: SelectEvent<T>, item: T]Fires when a row is clicked or chosen with Enter or Space, with the event and the node. Callevent.preventDefault()to keep the selection as it is.- toggle
[event: ToggleEvent<T>, item: T]Fires before a row expands or collapses from a click or an arrow key, with the event and the node. Callevent.preventDefault()to stop it.
Slots
- default
{ items: FlattenedItem<T>[]; modelValue: Model | null | undefined; expanded: string[]; }The rows, with{ items, modelValue, expanded }. Render aTreeItemfor each ofitems, or aTreeVirtualizer.
Exposed
- expandAll
() => voidExpands every node that has children.- collapseAll
() => voidCollapses every node.- scrollToKey
(key: string) => booleanScrolls a visible node into view, rendering it first when virtualized, and returns whether it is visible.
Props
- item*
FlattenedItem<T>One of the flattened rows from the tree's default slot. Key the loop by its_id.- disabled
booleanDisables the row. A node withdisabled: trueis disabled already.- as
stringThe element to render,liby default anddivin a virtualized tree.
Emits
- select
[event: SelectEvent<T>]Fires when the row is clicked or chosen with Enter or Space. Callevent.preventDefault()to keep the selection as it is.- toggle
[event: ToggleEvent<T>]Fires before the row expands or collapses. Callevent.preventDefault()to stop it.
Slots
- default
TreeItemSlotProps<T>The row's content, with{ item, level, expanded, selected, checked, disabled, loading, hasChildren, select, toggle }, such asTreeItemToggle,TreeItemCheckbox,TreeItemIconandTreeItemLabel.
The chevron of a node with children. It is drawn, not a control, so it takes no focus. A click on it opens or closes the node without selecting or checking it.
Slots
- default
{ expanded: boolean; }The icon of a node with children, with{ expanded }; a chevron that turns when the node opens. A spinner replaces it while the node isloading, and a leaf keeps the space empty so labels line up.
The row's checkbox in checkbox mode, checked, unchecked or indeterminate. It is drawn, not a control, so it takes no focus; the row carries aria-checked. A click on it checks without expanding.
Slots
- default
{}An icon before the label, sized by the tree and hidden from screen readers. It turns--primarywhen the row is selected.
Slots
- default
{}The row's text. It takes the free space and truncates with an ellipsis.
Props
- overscan
12 numberRows rendered past each edge of the view.- estimateSize
undefined numberRow height in pixels. Measured from--tree-item-heightby default, again when the tree first shows or its size changes.- textContent
undefined ((item: T) => string)The text typeahead matches for a node, since only the rows near the view are in the page. The node'slabelby default.
Slots
- default
{ item: FlattenedItem<T>; }One row, with{ item }: render aTreeItemfor it.
@/components/ui/tree also exports getAncestorKeys(items, key, { getKey, getChildren }), the keys of a node's ancestors, and flattenTree(items, { getChildren }), every node depth first.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| tree | data-variant, data-size, data-disabled, data-virtual, data-checkbox | The element with role="tree", a ul, or a div when virtualized. Receives class and attributes. |
| tree-item | data-key, data-expanded, data-selected, data-checked, data-indeterminate, data-loading, data-disabled, data-active | A row, with role="treeitem". data-selected marks a selected row, data-checked a checked one in checkbox mode, and data-active the row Tab enters on. |
| tree-item-toggle | data-state | The chevron, open or closed, or the empty space of a leaf. |
| tree-item-checkbox | data-state, data-size, data-disabled | The checkbox in checkbox mode: checked, unchecked or indeterminate. |
| tree-item-icon | — | The icon before the label. |
| tree-item-label | — | The row's text. |
CSS variables
Tree sets these from size, and rows read them. Override one with a class on Tree.
| Variable | Default | Description |
|---|---|---|
| --tree-item-height | var(--control-height-md) | A row's minimum height; a virtualized row's exact height. |
| --tree-item-px | var(--control-padding-md) | A row's side padding. |
| --tree-item-py | 8px | The padding above and below a row's text. |
| --tree-item-gap | var(--control-gap-md) | The space between the chevron, checkbox, icon and label. |
| --tree-icon | var(--control-icon-md) | The size of the chevron and the icons. |
| --tree-indent | calc(var(--tree-icon) + var(--tree-item-gap)) | How far each level moves in. |
Accessibility
The tree follows the APG tree view pattern. Rows are a flat list of treeitems with aria-level, aria-setsize and aria-posinset, so screen readers announce "level 2, 3 of 5" as in a nested tree. A folder has aria-expanded, a loading one aria-busy.
- One tab stop. Tab enters on the selected row, or the last focused one.
- In a single-select tree only the selected row has
aria-selected; withmultiple, every row has it,trueorfalse. Checkbox mode usesaria-checked,mixedfor a half-checked folder. - The chevron and the checkbox are drawn, not buttons, and hidden from screen readers: the row is the control.
- Name the tree with
aria-label, or put it in a Field.
Keyboard
Left and Right swap in a right-to-left tree.
| Key | Action |
|---|---|
| ArrowDown / ArrowUp | Moves to the next or previous visible row, skipping disabled ones. |
| ArrowRight | Opens a closed folder, or moves into an open one. |
| ArrowLeft | Closes an open folder, or moves to the parent. |
| Home / End | Moves to the first or last visible row. PageUp and PageDown do the same. |
| Enter / Space | Selects the row, or checks it in checkbox mode. Enter doesn't open folders. A Space typed mid-name searches on instead. |
| * | Opens every folder next to the focused row. |
| Shift + ArrowDown / ArrowUp | Extends the selection, with multiple and selection-behavior="replace". |
| A–Z | Moves to the next row starting with the letters typed, right after an arrow key or a Space too. |