Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Data

Tree

A finite hierarchical collection with expansion, selection, roving focus, and typeahead.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

Project files

Aurora web

Install

Run in your project
bunx --bun @getweini/cli@latest add tree

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import { ref } from 'vue'
import Tree from './components/ui/tree/Tree.vue'
import TreeGroup from './components/ui/tree/TreeGroup.vue'
import TreeItem from './components/ui/tree/TreeItem.vue'
import TreeItemTrigger from './components/ui/tree/TreeItemTrigger.vue'

const selected = ref<string>()
const expanded = ref<string[]>(['src'])
</script>

<template>
  <Tree v-model="selected" v-model:expanded="expanded" aria-label="Project files">
    <TreeItem value="src">
      <TreeItemTrigger>src</TreeItemTrigger>
      <TreeGroup>
        <TreeItem value="app"><TreeItemTrigger>App.vue</TreeItemTrigger></TreeItem>
        <TreeItem value="styles"><TreeItemTrigger>styles.css</TreeItemTrigger></TreeItem>
      </TreeGroup>
    </TreeItem>
  </Tree>
</template>

Tree renders all nested items in the DOM, so use VirtualList for very large flat collections. Arrow keys, Home and End, right-to-left navigation, and typeahead skip disabled nodes.

When to use it

File explorer

Navigate folders and files with expansion and roving focus.

Category picker

Select one or several nodes within a finite hierarchy.

More examples

File explorer

Nest TreeGroup within an expandable item and bind both selection and expansion.

File explorer
<script setup lang="ts">
import { ref } from 'vue'
import Tree from './components/ui/tree/Tree.vue'
import TreeGroup from './components/ui/tree/TreeGroup.vue'
import TreeItem from './components/ui/tree/TreeItem.vue'
import TreeItemTrigger from './components/ui/tree/TreeItemTrigger.vue'

const selected = ref<string>()
const expanded = ref<string[]>(['src'])
</script>

<template>
  <Tree v-model="selected" v-model:expanded="expanded" aria-label="Project files">
    <TreeItem value="src">
      <TreeItemTrigger>src</TreeItemTrigger>
      <TreeGroup>
        <TreeItem value="app"><TreeItemTrigger>App.vue</TreeItemTrigger></TreeItem>
        <TreeItem value="styles"><TreeItemTrigger>styles.css</TreeItemTrigger></TreeItem>
      </TreeGroup>
    </TreeItem>
  </Tree>
</template>

Multiple categories

An array model collects selections from different branches.

Multiple categories
<script setup lang="ts">
import { ref } from 'vue'
import Tree from './components/ui/tree/Tree.vue'
import TreeGroup from './components/ui/tree/TreeGroup.vue'
import TreeItem from './components/ui/tree/TreeItem.vue'
import TreeItemTrigger from './components/ui/tree/TreeItemTrigger.vue'

const selected = ref<string[]>([])
</script>

<template>
  <Tree v-model="selected" selection-mode="multiple" aria-label="Topics">
    <TreeItem value="science">
      <TreeItemTrigger>Science</TreeItemTrigger>
      <TreeGroup>
        <TreeItem value="physics"><TreeItemTrigger>Physics</TreeItemTrigger></TreeItem>
        <TreeItem value="biology"><TreeItemTrigger>Biology</TreeItemTrigger></TreeItem>
      </TreeGroup>
    </TreeItem>
  </Tree>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Tree

Complete API for Tree
NameType or signatureDefaultWhat it does
modelValuemodelTreeSelectionValue | undefinedNot setCurrent value. Use v-model to keep it in sync with your page.
defaultValuepropTreeSelectionValue | undefinedNot setStarting value when the parent does not control the value.
expandedmodelstring[] | undefinedNot setCurrent expanded value. Use the matching v-model binding to update it.
defaultExpandedpropstring[] | undefinedNot setStarting expanded state when the parent does not control it.
selectionModepropTreeSelectionMode | undefined"single"Choose whether one or several items can be selected.
dirprop"ltr" | "rtl" | undefined"ltr"Set the text direction used for keyboard and layout behavior.
update:modelValueevent[value: TreeSelectionValue]—Requests a new model value from the parent.
valueChangeevent[value: TreeSelectionValue]—Emitted after this value or state changes.
update:expandedevent[value: string[]]—Requests a new expanded value from the parent.
expandedChangeevent[value: string[]]—Emitted after this value or state changes.
defaultslot() => unknownRequiredContent shown inside Tree.

TreeGroup

Complete API for TreeGroup
NameType or signatureDefaultWhat it does
defaultslot() => unknownRequiredContent shown inside TreeGroup.

TreeItem

Complete API for TreeItem
NameType or signatureDefaultWhat it does
valuepropstringRequiredValue represented by this control or option.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
textValuepropstring | undefinedNot setPlain text used for search, typeahead, or an accessible label.
defaultslot() => unknownRequiredContent shown inside TreeItem.

TreeItemTrigger

Complete API for TreeItemTrigger
NameType or signatureDefaultWhat it does
defaultslot(props: { expanded: boolean; selected: boolean; disabled: boolean; }) => unknownRequiredContent shown inside TreeItemTrigger.
Public type definitions
Public types
// packages/frameworks/vue/components/tree/types.ts
// ------- TYPES -------

export type TreeSelectionMode = 'none' | 'single' | 'multiple'
export type TreeSelectionValue = string | string[]

export interface TreeProps {
  modelValue?: TreeSelectionValue
  defaultValue?: TreeSelectionValue
  expanded?: string[]
  defaultExpanded?: string[]
  selectionMode?: TreeSelectionMode
  dir?: 'ltr' | 'rtl'
}

export interface TreeItemProps {
  value: string
  disabled?: boolean
  textValue?: string
}

Implementation notes

  • Tree renders its finite nested collection in the DOM; for a very large flat collection, use VirtualList.
  • Keep values unique across every branch and use textValue when visible labels contain complex markup.

Accessibility and localization

  • Arrow keys, Home, End, and typeahead move focus; direction-aware arrows support RTL.

Source contract and editing guidance