Tree

new

Folders inside folders inside folders. A tree to browse, select or check nested items, with lazy folders and room for ten thousand nodes.

Demo
  • src
  • components
  • Header.vue
  • Sidebar.vue
  • App.vue
  • main.ts
  • package.json
  • README.md

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.

Multiple
  • Lisbon
  • IMG_4200.jpg
  • IMG_4207.jpg
  • IMG_4214.jpg
  • IMG_4221.jpg
  • Porto
  • IMG_4200.jpg
  • IMG_4207.jpg
  • IMG_4214.jpg

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.

Checkbox
  • Billing
  • View invoices
  • Issue refunds
  • Change payout account
  • Projects
  • Read
  • Write
  • Audit log

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.

Field
  • Content
  • Read posts
  • Publish posts
  • People
  • Invite members
  • Remove members

Checking a group grants everything in it.

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.

Mail folders
  • Sent

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.

Lazy

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.

Reveal

Filtering

Filter items yourself: keep the matches and the folders leading to them, and open those folders. The tree only renders what it gets.

Filter
  • Europe

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.

Git status
  • src3
  • router.tsmodified
  • session.tsadded
  • legacy-auth.tsdeleted
  • package.jsonmodified

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.

Composition
  • Maya ChenVP Engineering
  • Omar HaddadPlatform lead
  • Lena FischerSRE
  • Tom OkaforBackend
  • Inês DuarteDesign lead

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.

Context menu
  • Work
  • Roadmap
  • 1:1 agenda
  • Hiring plan
  • Inbox

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.

Virtual

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.
  • getChildren can'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, or contextmenu for menus.
  • Typeahead matches a row's whole text, everything after the label included. In a virtualized tree it matches TreeVirtualizer's text-content.
  • Enter, and outside a virtualized tree the arrow keys, Home, End, PageUp and PageDown, stop at the row, so a @keydown listener 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.

@/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-slotAttributesDescription
treedata-variant, data-size, data-disabled, data-virtual, data-checkboxThe element with role="tree", a ul, or a div when virtualized. Receives class and attributes.
tree-itemdata-key, data-expanded, data-selected, data-checked, data-indeterminate, data-loading, data-disabled, data-activeA 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-toggledata-stateThe chevron, open or closed, or the empty space of a leaf.
tree-item-checkboxdata-state, data-size, data-disabledThe 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.

VariableDefaultDescription
--tree-item-heightvar(--control-height-md)A row's minimum height; a virtualized row's exact height.
--tree-item-pxvar(--control-padding-md)A row's side padding.
--tree-item-py8pxThe padding above and below a row's text.
--tree-item-gapvar(--control-gap-md)The space between the chevron, checkbox, icon and label.
--tree-iconvar(--control-icon-md)The size of the chevron and the icons.
--tree-indentcalc(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; with multiple, every row has it, true or false. Checkbox mode uses aria-checked, mixed for 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.

KeyAction
ArrowDown / ArrowUpMoves to the next or previous visible row, skipping disabled ones.
ArrowRightOpens a closed folder, or moves into an open one.
ArrowLeftCloses an open folder, or moves to the parent.
Home / EndMoves to the first or last visible row. PageUp and PageDown do the same.
Enter / SpaceSelects 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 / ArrowUpExtends the selection, with multiple and selection-behavior="replace".
A–ZMoves to the next row starting with the letters typed, right after an arrow key or a Space too.

Changelog

  1. registry 0.21.0

    b073de0 — New DataTree: a tree drawn from data over the Tree parts, as DataTable is over Table. It takes Tree's props, draws each row from the node's icon and label (with a checkbox in checkbox mode, or your own through the item slot), and shows loading (skeleton rows), empty and error states in its frame through loading, empty and error and their slots, error first. virtualize renders only the rows near the view. v-model and v-model:expanded survive a state.

    e5495ef — size works the same way everywhere. Every component exports its size type (AlertSize, BadgeSize, CardSize, CheckboxSize, RadioSize, SwitchSize, EmptySize, InputFloatingSize, ItemSize, ListboxSize, SeparatorSize, SliderSize, StepperSize, TabsSize, TextareaSize, TimelineSize) and the props take it without null; Button-based parts take ButtonSize, Input TextControlSize, SelectTrigger SelectSize and Tree TreeSize. ToggleGroup and ToolbarToggleGroup carry data-size on the group as well. Table's row heights moved into tableSize, so a class on DataTable's ui.table overrides --table-row-h at every size, not only at md.

  2. registry 0.16.0

    df7e5fd — A click on a Tree folder's chevron only opens or closes it. It used to select the row as well, and in checkbox mode check the whole folder, so a folder couldn't be opened without changing what was checked.

    In checkbox mode a click checks only on TreeItemCheckbox. A click on the rest of the row opens or closes a folder, as in a tree without checkboxes, and does nothing on a leaf; Space still checks the focused row.

  3. registry 0.15.0

    d09f26a — Pressable parts ripple on their own: Button, Toggle, ToggleGroupItem, Item as a link or a button, the calendar days, tabs, accordion, menubar and navigation menu triggers, the items of Menu, Menubar, Select, Combobox, Command, DrawerMenu, Listbox and Tree, and the clear buttons of TagsInput and Combobox. Each imports the directive from @/lib/ripple, so add brings the ripple item along and nothing needs registering. On menu, listbox and tree rows the wave replaces the pressed layer, as state-layer already did. Bind v-ripple="false" on a Button to turn one off, or set --kappa-ripple: none on :root to turn them all off.

  4. registry 0.14.0

    b8167cf — Tree no longer draws its rows: render a TreeItem for each of the default slot's items and fill it with TreeItemToggle, TreeItemCheckbox, TreeItemIcon, TreeItemLabel or anything else, as with Reka's TreeRoot. The item, item-leading, item-label and item-trailing slots, TreeItem's leading, label and trailing slots, and label-key are gone; the row's state comes with TreeItem's slot. Virtualization is a part: put a TreeVirtualizer in a tree rendered as="div" with a height, instead of virtualize; its text-content gives typeahead each node's text. checkbox stays a selection mode (multiple, cascade, aria-checked) and no longer adds checkboxes by itself.

  5. registry 0.13.0

    936ab40 — New InputDate and InputDateRange: segmented date fields over Reka UI's DateField and DateRangeField, in Input's five variants and five sizes, with optional time segments, min-value/max-value, is-date-unavailable, loading and Field wiring. Inside an InputGroup they drop their own frame and take the group's variant and size. Pasting an ISO date (2025-03-14, or 2025-03-14T09:30) fills every segment, and Enter submits the form through its submit button, like a native date input. InputDateRange submits name[start] and name[end] as ISO dates, empty until that end is filled, and required needs both.

    InputTime and InputTimeRange get the same fixes. focus and blur now fire once when focus enters or leaves the field, so a form library's validate-on-blur runs; before, they never fired. Clicking the frame outside the segments focuses the first one, Enter submits the form, and changing granularity or hour-cycle after mount rebuilds the segments instead of leaving stale ones. InputTimeRange with name now submits name[start] and name[end] instead of one start - end field, which read undefined - undefined while empty and never failed required. If your server reads the old field, read the two new ones.

    00b6660 — New Tree: nested items to browse, select or check, over Reka UI's Tree, with TreeItem, TreeItemToggle, TreeItemCheckbox, TreeItemIcon and TreeItemLabel for rows of your own. Pass items and it renders each node's label, icon and chevron; children: [] makes a folder that loads later, and loading shows a spinner and sets aria-busy. It takes v-model (the nodes you passed in, never copies), v-model:expanded (keys), multiple, selection-behavior, checkbox with cascading checks, toggle-on-click, virtualize, name for plain form posts (required keeps an empty one from submitting), Field wiring, ghost (default) and outline variants and the five control sizes. It exposes expandAll, collapseAll and scrollToKey; getAncestorKeys and flattenTree come with it.

    The tree keeps its own selection instead of Reka UI's, which fixes a few things on the way: checking a child then its folder no longer leaves the child in the model twice, cascading checks follow getChildren to any depth and leave disabled nodes alone, a model echoed back with only leaves shows its folders checked, and a large selection no longer stalls on a deep watch. Typeahead works right after an arrow key or a Space, Tab enters on the selected row, only the selected row of a single-select tree has aria-selected, and a virtualized tree keeps focus when rows above the focused one open. Two nodes with the same key get a warning in development.

  6. registry 0.10.0

    e03458c — New InputTime and InputTimeRange: segmented time fields over Reka UI's TimeField and TimeRangeField, in Input's five variants and five sizes, with 12- or 24-hour cycles, hour, minute or second granularity, step, min-value/max-value, loading and Field wiring. Inside an InputGroup they drop their own frame and take the group's variant and size.