---
title: "Tree"
description: "A tree component built on Nuxt UI Tree, adding search, lazy loading, toolbar, checkboxes, and parent/child strategy."
canonical_url: "https://nuxt.mhaibaraai.cn/en/docs/components/tree"
---
# Tree
> A tree component built on Nuxt UI Tree, adding search, lazy loading, toolbar, checkboxes, and parent/child strategy.
## Introduction
`MTree` is a thin wrapper over Nuxt UI `Tree`, fully passing through all its props, events, and slots while adding several enhancements: search filtering with highlight, async lazy loading, a toolbar (expand/collapse toggle, tri-state select all), checkbox multi-select with parent/child strategy (cascade / isolated), key binding (`v-model:selectedKeys`), an imperative API, and selection categorization. Tree data normalization, filtering, and traversal reuse the `Tree` utility methods from `@movk/core`.
> [!NOTE]
> See: https://ui.nuxt.com/docs/components/tree
>
> Built on Nuxt UI's Tree component — all native props and slots are fully passed through
## Usage
Pass `items` to render a hierarchical structure. Node `defaultExpanded` controls the initial expansion, and `v-model` binds the selected node:
```vue
```
### `defaultExpanded` Default Expansion
`defaultExpanded` derives the initially expanded parent nodes from a strategy, falling back to the node's own `defaultExpanded` flag. Pass `true` to expand all parents, a `number` to expand only parents with depth less than that value, or a function for custom logic per node and depth:
```vue
```
### `searchable` Search Filtering
`searchable` renders a search input at the top, prunes the tree by keyword while preserving ancestor chains for matching nodes. `highlight` is enabled by default, highlighting matched text and auto-expanding on match. `filter` allows a custom match predicate. `search` supports `v-model:search` two-way binding of the keyword:
```vue
```
### `checkable` Checkbox Cascade
`checkable` renders a checkbox before each node, internally enables `multiple` with parent/child cascade and indeterminate state bubbling. `v-model` collects the selected node array. Checkboxes coexist with node `icon` and parent folder icons:
```vue
```
> [!NOTE]
>
> checkable
>
> is syntactic sugar for
>
> multiple
>
> +
>
> strategy
>
> (default
>
> cascade
>
> ). Use
>
> multiple
>
> instead when you need multi-select without rendering checkboxes.
### `multiple` Multiple Selection
`multiple` enables multi-select without rendering checkboxes. Clicking a node accumulates the selection. `v-model` collects the selected node array:
```vue
```
### `strategy` Parent/Child Strategy
`strategy` controls the parent/child check relationship in multi-select / `checkable` mode. `cascade` (default) cascades parent/child and re-fills the parent when all children are selected. `isolated` keeps parent and child independent — indeterminate state does not bubble:
```vue
```
### `selectedKeys` Key Binding
`selectedKeys` two-way binds the selection using an array of node keys — useful for re-populating from the backend or syncing with routes. `v-model:selectedKeys` and `v-model` are interoperable. Keys are derived from `getKey` / `labelKey`:
```vue
```
### `toolbar` Toolbar
`toolbar` renders a top toolbar with expand/collapse toggle buttons. When `searchable` is set, it embeds a clearable search input. When `checkable` is set, it adds a tri-state select-all checkbox and selection count:
```vue
```
> [!NOTE]
>
> The toolbar's select-all count is based on
>
> leaves
>
> : in cascade mode, selecting a parent brings in child keys. Counting by leaves avoids double counting.
### `lazy` Async Lazy Loading
`lazy` works with `loadChildren` — expanding an unloaded parent node fetches child nodes and displays a loading state. The `isLeaf` flag on a node marks it as a leaf, preventing expansion placeholder rendering:
```vue [ComponentsTreeLazyExample.vue]
```
### `childrenKey` Field Mapping
`childrenKey` normalizes the backend's child node field to `children`. `labelKey` specifies the display field, eliminating the need to pre-transform data structures:
```vue
```
### `labelKey` Dot-Path Value Extraction
`labelKey` specifies the node display field, supporting dot-path deep extraction of nested fields like `meta.title`. Key derivation, search, and highlight all use the same path:
```vue
```
> [!NOTE]
>
> The dot-path must align with UTree's internal value extraction. Only dot notation (
>
> a.b.c
>
> ) is supported — bracket notation (
>
> a[0].b
>
> ) is not.
### `virtualize` Virtual Scrolling
`virtualize` passes through Nuxt UI Tree's virtualization capability, rendering only visible nodes — suitable for large data sets:
```vue [ComponentsTreeVirtualizeExample.vue]
```
### `color` Primary Color
`color` passes through Nuxt UI Tree's primary color, applying to selected node text color and keyboard focus ring. The example pre-selects a node for visual reference:
```vue
```
> [!NOTE]
>
> UTree's
>
> color
>
> only applies to selected node text and focus ring. No visible change occurs when no node is selected. Single-color icons (e.g., lucide) inherit the text color; multi-color icons (e.g., vscode-icons) maintain their own coloring.
### `trailingIcon` Trailing Icon
`trailingIcon` replaces the expand indicator icon at the end of parent nodes (default `i-lucide-chevron-down`). `item.trailingIcon` on node data takes higher priority:
```vue
```
### `expandedIcon` Expand Icon
`expandedIcon` / `collapsedIcon` customize the leading icon for parent nodes when expanded / collapsed (default `i-lucide-folder-open` / `i-lucide-folder`):
```vue
```
> [!NOTE]
>
> item.icon
>
> on a node takes higher priority than
>
> expandedIcon
>
> /
>
> collapsedIcon
>
> . Therefore, folders that need to switch icons based on expanded state should not set
>
> item.icon
>
> .
### `disabled` Disabled
`disabled` disables the entire tree, blocking click events on nodes, toolbar controls, and checkboxes for expand, collapse, and select operations. Per-node `item.disabled` disables that node and its entire subtree — freezing expansion state and disabling checkboxes within the subtree:
```vue
```
> [!NOTE]
>
> Imperative API methods (
>
> expandToDepth
>
> ,
>
> selectAll
>
> , etc.) are explicit calls and are not affected by
>
> disabled
>
> .
>
> disabled
>
> only intercepts user clicks and toolbar interactions.
## Examples
### Custom Node
Customize node content via passed-through slots like `item-trailing`. Uncovered slots are still rendered by Nuxt UI Tree's defaults:
```vue [ComponentsTreeSlotExample.vue]
```
### Custom Toolbar
`toolbar-leading` / `toolbar-trailing` append content to the start/end of the default toolbar. Use the `#toolbar` slot for full control — its scope exposes methods and state like `toggleExpand`, `selectAll`, `clear`, and `selectionSummary`:
```vue [ComponentsTreeCustomToolbarExample.vue]
```
### Imperative Control
Obtain the component instance via `useTemplateRef` and call methods like `expandToDepth`, `collapseAll`, `selectAll`, and `clearSelection` to control the tree:
```vue [ComponentsTreeImperativeExample.vue]
```
### Selection Categorization
The instance's reactive `treeSelection` returns selection categories: `leaves` (selected leaves), `parents` (fully selected parents), `halfSelected` (indeterminate parents), and `strictlyChecked` (excludes children selected via parent cascade):
```vue [ComponentsTreeSelectionExample.vue]