Skip to content

Tree

Browse and select items in a nested list.

Demos

Size
Variant
Selection highlight

Button.vue selected

Usage

vue
<script setup lang="ts">
import { Accordion } from '~/components/ui/accordion'

const items = [
  { value: 'source', label: 'Do I own the source?', content: 'Yes. Copy and adapt the files.' },
]
</script>

<template>
  <Accordion :items="items" />
</template>

Selection highlight

Use selection-highlight to control the width of the selected area and sliding hover:

  • full: spans the row width, including indentation.
  • indented: starts after the node's indentation and fills the remaining content width.
  • label: wraps the label text.

Switch between these scopes with Selection highlight in the playground above. This controls appearance; selection-mode controls whether users can select one, multiple, or no nodes.

vue
<AppLayout :viewport="false" scroll="page">
  <template #header>Workspace</template>
  <template #left><ProjectNavigation /></template>
  <ProjectList />
  <template #footer>2 projects</template>
</AppLayout>

Multiple selection

Select a branch to select its descendants. A partial selection shows a dash, and check marks stay at the trailing edge. Disclosure buttons expand independently from selection.

1 selected

vue
<AppLayout :layout="{ header: 'full', footer: 'content' }">
  <template #left><ProjectNavigation /></template>
  <ProjectList />
  <template #right><ProjectDetails /></template>
</AppLayout>

Loading branches

Use has-children for a branch that has not loaded yet. Add its key to loading-keys during the request, then update its children. The disclosure shows progress while you load data.

No item selected

Large trees

This example renders a window of 1,000 files. Row height follows size, including touch targets. Arrow keys and typeahead keep working; Home and End move to the first and last enabled item.

1,000 files

No item selected

Set virtualize to true or an options object. IPEX calculates the item height from the selected size and its 2px row spacing. Override itemHeight when you provide custom row geometry; it must include that spacing.

Empty state

Use labels.empty for a message or the empty slot for custom content.

No items to display.

Installation

Complete the shared installation. Copy Tree.vue and index.ts into app/components/ui/tree/.

API

Variants and defaults

PropValuesDefault
variantsoft, subtlesoft
sizexs, sm, md, lg, xlsm

soft uses the same neutral selection fill as the sidebar. subtle adds an inset border. Tree selection defaults to the full row; choose indented or label when the selected area should follow the hierarchy more closely. Focus rings appear for keyboard navigation. Hover moves between nodes with a sliding highlight that follows the same boundary.

Row height, disclosure target, icons, text, padding, and corners scale together. Branches and leaves at the same depth share one label column. Default indent steps are 12/16/20/24/28px for xs/sm/md/lg/xl; an explicit indent overrides them.

Models

ModelTypeDefaultDescription
v-modelTreeKey | TreeKey[] | nullnullSelected key in single mode or selected keys in multiple mode.
v-model:expandedTreeKey[]defaultExpandedExpanded branch keys.

Props

PropTypeDefaultDescription
itemsreadonly T[]requiredNested tree data.
itemKeykeyof T | (item) => TreeKeyrequiredStable, globally unique item key.
labelKeykeyof T | (item) => unknown"label"Label accessor.
childrenKeykeyof T | (item) => T[]"children"Child collection accessor.
disabledKeykeyof T | (item) => unknown"disabled"Disabled state accessor.
selectableKeykeyof T | (item) => unknown"selectable"Selectable state accessor.
defaultExpandedKeykeyof T | (item) => unknown"defaultExpanded"Initial expansion accessor.
slotKeykeyof T | (item) => unknown"slot"Dynamic item slot accessor.
textValue(item: T) => stringlabel textText used by typeahead.
hasChildren(item: T) => boolean-Marks a branch before its children are loaded.
defaultValueTreeSelectionnullInitial uncontrolled selection.
defaultExpandedTreeKey[]item defaultsInitial uncontrolled expansion.
loadingKeysreadonly TreeKey[][]Branches currently loading children.
selectionMode"none" | "single" | "multiple""single"Selection mode.
selectionBehavior"replace" | "toggle""toggle"Multiple-selection behavior without a modifier key.
selectionPropagation"none" | "up" | "down" | "both""none"Branch selection propagation.
selectionHighlight"full" | "indented" | "label""full"Visual boundary used by ui.selection; ARIA selection remains on the complete item.
selectOnFocusbooleanfalseSelects a node when roving focus reaches it.
expandOnClickbooleantrueToggles a branch when its non-interactive row content is clicked. Toggle buttons always work.
disabledbooleanfalseDisables the tree.
readOnlybooleanfalseBlocks selection changes while preserving navigation and expansion.
typeaheadbooleantrueEnables printable-character navigation.
transitionbooleantrueEnables built-in branch row motion. Ignored during virtualization.
indentnumbersize-dependentIndentation in pixels for each nested level.
orientation"vertical" | "horizontal""vertical"Navigation orientation.
dir"ltr" | "rtl""ltr"Text direction and horizontal Arrow behavior.
virtualizeboolean | TreeVirtualOptionsfalseEnables fixed-height row virtualization.
ariaLabelstring"Tree"Accessible tree label.
ariaLabelledbystring-Id of an accessible label.
ariaDescribedbystring-Id of supporting text.
labelsTreeLabels<T>-Expand, collapse, loading, and empty labels.
asstring | Component"div"Root element or component.
uiTreeUi-Classes for structural parts.

TreeVirtualOptions accepts height, itemHeight, and overscan numbers.

Slots

SlotPropsDescription
itemitem, node, actions, toggleProps, treeReplaces generated content inside every row.
item-[name]same as itemContent replacement selected by an item's slot value.
toggleitem, node, actions, toggleProps, treeToggle content inside the generated button.
indicatoritem, node, actions, toggleProps, treeSelection indicator.
iconitem, node, actions, toggleProps, treeItem icon.
labelitem, node, actions, toggleProps, treeItem content. May contain a title and supporting text.
trailingitem, node, actions, toggleProps, treeTrailing content or controls.
loadingitem, node, actions, toggleProps, treeExpanded lazy-branch loading content.
emptytreeEmpty state.

node exposes key, parent, depth, sibling position, label, and branch, expansion, selection, indeterminate, focus, disabled, selectable, and loading state.

Events

EventPayloadDescription
selection-change(value, details)Fired before selection updates.
expanded-change(keys, details)Fired before expansion updates. details.expanded reports the requested branch state.
focus-change(key, details)Fired before the roving focus key changes.
activate(item, details)Fired on row click, touch, or Enter.

Event details include key, item, reason, the original event when available, and cancel(). Calling cancel() in a change event prevents its model update.

Keyboard

KeyBehavior
ArrowDown / ArrowUpMove through visible items in a vertical tree.
ArrowRightExpand a collapsed branch, then move to its first child. In RTL, ArrowLeft does this.
ArrowLeftCollapse an expanded branch, then move to its parent. In RTL, ArrowRight does this.
Home / EndMove to the first/last enabled visible item.
*Expand all enabled branches at the current level.
SpaceSelect or toggle the focused item.
EnterSelect and activate the focused item.
Shift + movement Arrow or Home / EndExtend a multiple-selection range from its anchor.
Ctrl+A / Cmd+ASelect all enabled items in multiple mode.
printable charactersMove to the next visible label matching the typed prefix.

Horizontal orientation maps movement to Left/Right and expansion to Down/Up. One visible enabled item participates in the page tab order.

In multiple mode, Shift + click selects the visible range from the last selection anchor. Ctrl / Cmd + Shift + click adds that range to the current selection.