Data Tree
newA tree drawn from data, with rows from each node's label and icon, loading, empty and error states, and virtualization by one prop.
No file open
Open Props in the corner of the example to try size and disabled.
Installation
Usage
<script setup lang="ts">
import { DataTree } from '@/components/ui/data-tree'
const files = [
{ id: 'src', label: 'src', children: [{ id: 'src/App.vue', label: 'App.vue' }] },
{ id: 'package.json', label: 'package.json' },
]
const opened = shallowRef()
</script>
<template>
<DataTree v-model="opened" :items="files" aria-label="Files" />
</template>
DataTree is to Tree what DataTable is to Table. It takes Tree's props and draws the rows itself: a chevron, a checkbox with checkbox, the node's icon and its label. It also draws the states a tree of fetched data goes through. For rows of another shape, use the item slot; to wrap each row in something else, such as a context menu, use Tree.
v-model and v-model:expanded work as on Tree, and they survive a state: a tree that empties and fills again keeps what was open and selected.
Examples
Loading, empty and error
The order is error, then loading, then empty, then the tree. With no items, loading shows skeleton rows; with items, the tree stays and the root turns aria-busy. With no items and not loading, the empty message shows. error shows ahead of everything: pass the error itself, and the error slot gets it as { error }, the place for an ErrorState. A state sits in the tree's frame, next to the tree rather than inside it.
Virtualization
virtualize renders only the rows near the view. Give DataTree a height; the tree scrolls inside the frame. Pass { overscan, estimateSize, textContent } to tune the TreeVirtualizer.
10,100 nodes, about 20 rendered. Try End, or type a name.
Custom rows
The item slot replaces a row's content and gets its state. Build it from TreeItemToggle, TreeItemIcon, TreeItemLabel and TreeItemCheckbox.
API Reference
DataTree
| Prop | Default | Type and description |
|---|---|---|
| items* | — | T[]The top-level nodes, as on Tree. A row shows a node's |
| defaultValue | undefined | ModelThe starting selection when |
| multiple | — | MLets more than one node be selected; |
| defaultExpanded | — | string[]The starting expanded keys when |
| selectionBehavior | "toggle" | "toggle" | "replace"
|
| checkbox | — | booleanCheckbox mode, with a checkbox in every default row. Turns on |
| cascade | undefined | booleanChecking a parent checks its subtree, as on Tree. 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
|
| name | — | stringSubmits the selected keys with their form under this name. While a state shows there is no tree, so nothing is submitted. |
| id | — | stringOverrides the |
| disabled | — | booleanDisables every row. Also set by a disabled field. |
| required | — | booleanMarks the tree required, as on Tree. Also set by a required field. |
| dir | — | "ltr" | "rtl"Reading direction for Left and Right. |
| variant | — | "ghost" | "outline" | null
|
| size | "md" | TreeSizeSets the rows' height, padding, gap, icons, indent and text, and the states' padding, from |
| virtualize | false | DataTreeVirtualize<T>Renders only the rows near the view. |
| loading | false | booleanWith no items, shows the loading state, skeleton rows by default. With items, the tree stays and the root is |
| loadingRows | 3 | numberHow many skeleton rows the loading state shows. 3 by default. |
| empty | "No items" | stringThe message when there are no items. |
| error | — | unknownShows the error state in place of the tree, ahead of loading and empty. Any value but |
| modelValue | — | Model | nullThe selected node, or an array of them with |
| expanded | — | string[]The keys of the expanded nodes, bound with |
| Event | Payload and description |
|---|---|
| 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, with the event and the node. Call |
| update:modelValue | [value: Model | null | undefined]Fires when the selection changes. |
| update:expanded | [value: string[] | undefined]Fires when a node expands or collapses, with the expanded keys. |
| Slot | Scope and description |
|---|---|
| item | TreeItemSlotProps<T>A row's content, with the row's state ( |
| empty | anyThe empty state. The |
| loading | anyThe loading state. Skeleton rows by default. |
| error | { error: unknown; }The error state, 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; |
Props
- items*
T[]The top-level nodes, as on Tree. A row shows a node'siconandlabel; use theitemslot for anything else. No items shows the empty state.- defaultValue
undefined ModelThe starting selection whenv-modelis not used.- multiple
MLets more than one node be selected;v-modelis then an array.- defaultExpanded
string[]The starting expanded keys whenv-model:expandedis not used. Left out, nodes withdefaultExpanded: truestart expanded, read from the first items the tree shows.- selectionBehavior
"toggle" "toggle" | "replace"toggleorreplace, as on [Tree](/docs/components/tree#api-reference).- checkbox
booleanCheckbox mode, with a checkbox in every default row. Turns onmultipleandcascade.- cascade
undefined booleanChecking a parent checks its subtree, as on Tree. On by default withcheckbox.- getKey
((item: T) => string)Returns a node's unique key, a string. By defaultid, thenvalue, thenlabel.- 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.- name
stringSubmits the selected keys with their form under this name. While a state shows there is no tree, so nothing is submitted.- id
stringOverrides theidtaken from a surrounding field.- disabled
booleanDisables every row. Also set by a disabled field.- required
booleanMarks the tree required, as on Tree. Also set by a required field.- dir
"ltr" | "rtl"Reading direction for Left and Right.- variant
"ghost" | "outline" | nullghostdraws no frame;outlinedraws a card-like frame around the tree and its states.- size
"md" TreeSizeSets the rows' height, padding, gap, icons, indent and text, and the states' padding, fromxstoxl.mdis the default.- virtualize
false DataTreeVirtualize<T>Renders only the rows near the view.true, or{ overscan, estimateSize, textContent }for the TreeVirtualizer. Give DataTree a height, such asclass="h-80"; the tree scrolls inside the frame.- loading
false booleanWith no items, shows the loading state, skeleton rows by default. With items, the tree stays and the root isaria-busy.- loadingRows
3 numberHow many skeleton rows the loading state shows. 3 by default.- empty
"No items" stringThe message when there are no items.No itemsby default.- error
unknownShows the error state in place of the tree, ahead of loading and empty. Any value butundefined,nullandfalsecounts, so pass the error itself; a string is the default message.- modelValue
Model | nullThe selected node, or an array of them withmultiple, bound withv-model. Kept while a state replaces the tree.- expanded
string[]The keys of the expanded nodes, bound withv-model:expanded. Kept while a state replaces the tree.
Emits
- 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, with the event and the node. Callevent.preventDefault()to stop it.- update:modelValue
[value: Model | null | undefined]Fires when the selection changes.- update:expanded
[value: string[] | undefined]Fires when a node expands or collapses, with the expanded keys.
Slots
- item
TreeItemSlotProps<T>A row's content, with the row's state (item,level,expanded,selected,checked,disabled,loading,hasChildren,select,toggle). Build it from the TreeItem parts.- empty
anyThe empty state. Theemptymessage by default.- loading
anyThe loading state. Skeleton rows by default.- error
{ error: unknown; }The error state, with{ error }. An alert with theerrorstring orSomething went wrongby default; put anErrorStatehere.
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;falsewhile a state shows.
Data attributes
The tree inside carries the Tree slots and attributes.
| data-slot | Attributes | Description |
|---|---|---|
| data-tree | data-size, data-variant | The root and the frame, aria-busy while loading. |
| data-tree-loading | — | The loading state. |
| data-tree-empty | — | The empty state. |
| data-tree-error | — | The error state. |
Accessibility
- A tree may only hold rows, so a state replaces the tree instead of going inside it.
aria-label,aria-labelledbyand a field's label reach the element with the tree role.- The default error message is an alert; the skeleton rows are hidden from screen readers.