BrutxUI

English

简体中文

English

简体中文

Appearance

TreeView ​

A recursive expandable hierarchical data visualization component with built-in folder/file icons, supporting keyboard navigation and controlled single/checkbox selection states.

Demo ​

Preview
src
components
Button.vue
Input.vue
index.ts
package.json

已选择：button

复选模式

docs
guide.md
api.md
faq.md
assets
logo.svg
cover.png

已勾选：1 项

Installation ​

pnpm dlx brutx-vue@latest add tree-view

Usage ​

vue
<script setup>
import { ref } from 'vue'
import { TreeView } from 'brutx-ui-vue'
import type { TreeNode } from 'brutx-ui-vue'

const nodes: TreeNode[] = [
    {
        id: 'src',
        label: 'src',
        children: [
            { id: 'button', label: 'Button.vue' },
            { id: 'input', label: 'Input.vue' },
        ],
    },
    { id: 'pkg', label: 'package.json' },
]

const selected = ref(null)
</script>

<template>
    <TreeView
        v-model="selected"
        :nodes="nodes"
        :default-expanded="['src']"
    />
</template>

Checkbox Mode ​

vue
<script setup>
import { ref } from 'vue'
import { TreeView } from 'brutx-ui-vue'
import type { TreeNode } from 'brutx-ui-vue'

const nodes: TreeNode[] = [
    {
        id: 'src',
        label: 'src',
        children: [
            { id: 'button', label: 'Button.vue' },
            { id: 'input', label: 'Input.vue', disabled: true },
        ],
    },
]

const checkedIds = ref<string[]>(['button'])
</script>

<template>
    <TreeView
        v-model:checked-ids="checkedIds"
        :nodes="nodes"
        selection-mode="checkbox"
        :default-expanded="['src']"
    />
</template>

Variants ​

selectionMode supports two selection modes:

VariantDescription
singleDefault single selection mode; clicking a node syncs the selected id via v-model
checkboxCheckbox mode; each node renders a Checkbox with cascading selection -- checking a parent selects all descendants; when only some descendants are checked, the parent shows an indeterminate state (aria-checked="mixed"). Checked items are two-way bound via v-model:checkedIds. Nodes with disabled: true cannot be checked

Data Types ​

ts
interface TreeNode {
    id: string            // Unique identifier
    label: string         // Display text
    icon?: string         // Node icon (reserved field, currently unused)
    children?: TreeNode[] // Child nodes (omit for leaf nodes)
    data?: unknown        // Custom attached data
    disabled?: boolean    // Whether disabled (cannot be checked in checkbox mode)
    isLeaf?: boolean      // Whether the node is a leaf (used in lazy mode to determine if expandable)
    loaded?: boolean      // Whether children have been loaded (marks lazy load completion)
    loading?: boolean     // Whether children are currently loading
    hidden?: boolean      // Whether the node is hidden (set by node filtering)
}

Note: Node icons are currently rendered automatically by the component based on type -- folder nodes use Folder / FolderOpen icons, leaf nodes use File icons. No manual specification is needed.

Exported Types ​

In addition to TreeNode, the component also exports the following types for TypeScript projects:

ts
import type { SelectionMode, CheckState } from 'brutx-ui-vue'

type SelectionMode = 'single' | 'checkbox'
type CheckState = 'checked' | 'unchecked' | 'indeterminate'

API Reference ​

TreeView

TreeView — Props
NameTypeDefaultDescription
nodes
Required
TreeNode<unknown>[]
—
The tree data source. Each node is described by an id, label, and optional fields such as children and disabled.
Details

Declared type

TreeNode<unknown>[]

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Default value details

Not declared
—

Source

TreeView.vue:13

packages/ui/src/components/tree-view/TreeView.vue

modelValue
Nullable
string | null | undefined
null
The id of the selected node, controlled with v-model; null means no node is selected.
Details

Declared type

string | null | undefined

Literal values

  • null

Default value details

Declaration
null

Source: packages/ui/src/components/tree-view/TreeView.vue

Resolved value
null

Source

TreeView.vue:14

packages/ui/src/components/tree-view/TreeView.vue

checkedIds
string[] | undefined
[]

Factory evaluated per instance

The ids of checked nodes in checkbox mode, controlled with v-model:checkedIds.
Details

Declared type

string[] | undefined

Default value details

Declaration
() => []

Source: packages/ui/src/components/tree-view/TreeView.vue

Resolved value
[]

Source

TreeView.vue:15

packages/ui/src/components/tree-view/TreeView.vue

selectionMode
SelectionMode | undefined
"single"
The selection mode: single selects one node, while checkbox allows multiple checked nodes.
Details

Declared type

SelectionMode | undefined

Literal values

  • "checkbox"
  • "single"

Referenced types

SelectionMode
Type definition — SelectionMode
export type SelectionMode = 'single' | 'checkbox'

Default value details

Declaration
'single'

Source: packages/ui/src/components/tree-view/TreeView.vue

Resolved value
"single"

Source

TreeView.vue:16

packages/ui/src/components/tree-view/TreeView.vue

defaultExpanded
string[] | undefined
[]

Factory evaluated per instance

Node ids expanded on initial render; subsequent expansion state is maintained internally.
Details

Declared type

string[] | undefined

Default value details

Declaration
() => []

Source: packages/ui/src/components/tree-view/TreeView.vue

Resolved value
[]

Source

TreeView.vue:17

packages/ui/src/components/tree-view/TreeView.vue

class
string | undefined
undefined
Custom CSS classes added to the tree root container.
Details

Declared type

string | undefined

Default value details

Declaration
undefined

Source: packages/ui/src/components/tree-view/TreeView.vue

Resolved value
undefined

Source

TreeView.vue:18

packages/ui/src/components/tree-view/TreeView.vue

draggable
boolean | undefined
false
Enables node drag-and-drop sorting and updates the node data after a drop.
Details

Declared type

boolean | undefined

Literal values

  • false
  • true

Default value details

Declaration
false

Source: packages/ui/src/components/tree-view/TreeView.vue

Resolved value
false

Source

TreeView.vue:21

packages/ui/src/components/tree-view/TreeView.vue

allowDrag
((node: TreeNode<unknown>) => boolean) | undefined
undefined
Decides whether dragging may start for a node; all nodes are draggable when omitted.
Details

Declared type

((node: TreeNode<unknown>) => boolean) | undefined

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Default value details

Declaration
undefined

Source: packages/ui/src/components/tree-view/TreeView.vue

Resolved value
undefined

Source

TreeView.vue:22

packages/ui/src/components/tree-view/TreeView.vue

allowDrop
((dragNode: TreeNode<unknown>, dropNode: TreeNode<unknown>, dropType: "before" | "after" | "inner") => boolean) | undefined
undefined
Decides whether a dragged node may be placed before, after, or inside a target node.
Details

Declared type

((dragNode: TreeNode<unknown>, dropNode: TreeNode<unknown>, dropType: "before" | "after" | "inner") => boolean) | undefined

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Default value details

Declaration
undefined

Source: packages/ui/src/components/tree-view/TreeView.vue

Resolved value
undefined

Source

TreeView.vue:23

packages/ui/src/components/tree-view/TreeView.vue

lazy
boolean | undefined
false
Enables lazy node loading and calls load when an unloaded node is expanded.
Details

Declared type

boolean | undefined

Literal values

  • false
  • true

Default value details

Declaration
false

Source: packages/ui/src/components/tree-view/TreeView.vue

Resolved value
false

Source

TreeView.vue:26

packages/ui/src/components/tree-view/TreeView.vue

load
((node: TreeNode<unknown>) => Promise<TreeNode<unknown>[]>) | undefined
undefined
Asynchronously loads children for a node; the returned nodes are written into the tree data.
Details

Declared type

((node: TreeNode<unknown>) => Promise<TreeNode<unknown>[]>) | undefined

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Default value details

Declaration
undefined

Source: packages/ui/src/components/tree-view/TreeView.vue

Resolved value
undefined

Source

TreeView.vue:27

packages/ui/src/components/tree-view/TreeView.vue

retryOnError
boolean | undefined
false
Shows a retry action after a load failure and requests that node again when activated.
Details

Declared type

boolean | undefined

Literal values

  • false
  • true

Default value details

Declaration
false

Source: packages/ui/src/components/tree-view/TreeView.vue

Resolved value
false

Source

TreeView.vue:28

packages/ui/src/components/tree-view/TreeView.vue

filterable
boolean | undefined
false
Enables node filtering; provide a query through the exposed filter method.
Details

Declared type

boolean | undefined

Literal values

  • false
  • true

Default value details

Declaration
false

Source: packages/ui/src/components/tree-view/TreeView.vue

Resolved value
false

Source

TreeView.vue:31

packages/ui/src/components/tree-view/TreeView.vue

filterMethod
((query: string, node: TreeNode<unknown>) => boolean) | undefined
undefined
Custom node matching rule. Return true to keep a node; when omitted, the query is matched against its label.
Details

Declared type

((query: string, node: TreeNode<unknown>) => boolean) | undefined

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Default value details

Declaration
undefined

Source: packages/ui/src/components/tree-view/TreeView.vue

Resolved value
undefined

Source

TreeView.vue:32

packages/ui/src/components/tree-view/TreeView.vue

TreeView — Events
NameSignature or typeDescription
@update:modelValue
[id: string | null]
Emits the new selected node id when selection changes, or null when selection is cleared.
Details

Declared type

[id: string | null]

Literal values

  • null

Source

TreeView.vue

packages/ui/src/components/tree-view/TreeView.vue

@select
[node: TreeNode<unknown>]
Emits the selected node as a TreeNode when the user selects it.
Details

Declared type

[node: TreeNode<unknown>]

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Source

TreeView.vue

packages/ui/src/components/tree-view/TreeView.vue

@expand
[id: string, expanded: boolean]
Emits a node id and its new expanded state when the node is expanded or collapsed.
Details

Declared type

[id: string, expanded: boolean]

Literal values

  • false
  • true

Source

TreeView.vue

packages/ui/src/components/tree-view/TreeView.vue

@update:checkedIds
[ids: string[]]
Emits the updated list of checked node ids when the checked set changes.
Details

Declared type

[ids: string[]]

Source

TreeView.vue

packages/ui/src/components/tree-view/TreeView.vue

@update:expanded
[ids: string[]]
Emits the updated list of expanded node ids when the expanded set changes.
Details

Declared type

[ids: string[]]

Source

TreeView.vue

packages/ui/src/components/tree-view/TreeView.vue

@update:nodes
[nodes: TreeNode<unknown>[]]
Emits the updated tree data after drag-and-drop changes the node order or parent.
Details

Declared type

[nodes: TreeNode<unknown>[]]

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Source

TreeView.vue

packages/ui/src/components/tree-view/TreeView.vue

@check
[node: TreeNode<unknown>, checked: boolean]
Emits the node and its new checked state when its checkbox changes.
Details

Declared type

[node: TreeNode<unknown>, checked: boolean]

Literal values

  • false
  • true

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Source

TreeView.vue

packages/ui/src/components/tree-view/TreeView.vue

@node-drag-start
[event: DragEvent, node: TreeNode<unknown>]
Emits the native DragEvent and dragged node when dragging starts.
Details

Declared type

[event: DragEvent, node: TreeNode<unknown>]

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Source

TreeView.vue

packages/ui/src/components/tree-view/TreeView.vue

@node-drag-enter
[event: DragEvent, node: TreeNode<unknown>]
Emits the DragEvent and node when the pointer enters that node during a drag.
Details

Declared type

[event: DragEvent, node: TreeNode<unknown>]

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Source

TreeView.vue

packages/ui/src/components/tree-view/TreeView.vue

@node-drag-leave
[event: DragEvent, node: TreeNode<unknown>]
Emits the DragEvent and node when the pointer leaves that node during a drag.
Details

Declared type

[event: DragEvent, node: TreeNode<unknown>]

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Source

TreeView.vue

packages/ui/src/components/tree-view/TreeView.vue

@node-drag-over
[event: DragEvent, node: TreeNode<unknown>]
Emits the DragEvent and node while the pointer moves over that node during a drag.
Details

Declared type

[event: DragEvent, node: TreeNode<unknown>]

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Source

TreeView.vue

packages/ui/src/components/tree-view/TreeView.vue

@node-drag-end
[event: DragEvent, node: TreeNode<unknown>]
Emits the DragEvent and dragged node when dragging ends.
Details

Declared type

[event: DragEvent, node: TreeNode<unknown>]

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Source

TreeView.vue

packages/ui/src/components/tree-view/TreeView.vue

@node-drop
[event: DragEvent, node: TreeNode<unknown>, dropType: "before" | "after" | "inner"]
Emits the DragEvent, target node, and before, after, or inner drop position after a successful drop.
Details

Declared type

[event: DragEvent, node: TreeNode<unknown>, dropType: "before" | "after" | "inner"]

Literal values

  • "after"
  • "before"
  • "inner"

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Source

TreeView.vue

packages/ui/src/components/tree-view/TreeView.vue

TreeView — Exposes
NameSignature or typeDescription
filter
(query: string) => void
Filters nodes by query text; pass an empty string to restore all nodes.
Details

Declared type

(query: string) => void

Source

TreeView.vue:463

packages/ui/src/components/tree-view/TreeView.vue

reloadNode
(nodeKey: string) => void
Reloads the children of the specified node to refresh its lazy-loaded data.
Details

Declared type

(nodeKey: string) => void

Source

TreeView.vue:464

packages/ui/src/components/tree-view/TreeView.vue

TreeViewNode

TreeViewNode — Props
NameTypeDefaultDescription
node
Required
TreeNode<unknown>
—
The tree node represented by this row.
Details

Declared type

TreeNode<unknown>

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Default value details

Not declared
—

Source

TreeViewNode.vue:17

packages/ui/src/components/tree-view/TreeViewNode.vue

selectedId
Nullable
string | null | undefined
null
The currently selected node id, used to determine whether this row is selected.
Details

Declared type

string | null | undefined

Literal values

  • null

Default value details

Declaration
null

Source: packages/ui/src/components/tree-view/TreeViewNode.vue

Resolved value
null

Source

TreeViewNode.vue:18

packages/ui/src/components/tree-view/TreeViewNode.vue

expandedIds
Required
Set<string>
—
The set of expanded node ids, used to determine this node’s expanded state.
Details

Declared type

Set<string>

Default value details

Not declared
—

Source

TreeViewNode.vue:19

packages/ui/src/components/tree-view/TreeViewNode.vue

depth
number | undefined
0
The node’s depth in the tree, used to calculate row indentation.
Details

Declared type

number | undefined

Default value details

Declaration
0

Source: packages/ui/src/components/tree-view/TreeViewNode.vue

Resolved value
0

Source

TreeViewNode.vue:20

packages/ui/src/components/tree-view/TreeViewNode.vue

isFirstRoot
boolean | undefined
false
Marks whether this is the first root node for root-row layout.
Details

Declared type

boolean | undefined

Literal values

  • false
  • true

Default value details

Declaration
false

Source: packages/ui/src/components/tree-view/TreeViewNode.vue

Resolved value
false

Source

TreeViewNode.vue:21

packages/ui/src/components/tree-view/TreeViewNode.vue

selectionMode
SelectionMode | undefined
"single"
The selection mode for this row, determining single selection or checkbox interaction.
Details

Declared type

SelectionMode | undefined

Literal values

  • "checkbox"
  • "single"

Referenced types

SelectionMode
Type definition — SelectionMode
export type SelectionMode = 'single' | 'checkbox'

Default value details

Declaration
'single'

Source: packages/ui/src/components/tree-view/TreeViewNode.vue

Resolved value
"single"

Source

TreeViewNode.vue:22

packages/ui/src/components/tree-view/TreeViewNode.vue

checkedIds
Set<string> | undefined
Factory evaluated per instance
The set of checked node ids, used to render checkbox state.
Details

Declared type

Set<string> | undefined

Default value details

Declaration
() => new Set()

Source: packages/ui/src/components/tree-view/TreeViewNode.vue

Resolution expression
() => new Set()

Source

TreeViewNode.vue:23

packages/ui/src/components/tree-view/TreeViewNode.vue

disabled
boolean | undefined
false
Disables selection, checking, and keyboard activation for this node.
Details

Declared type

boolean | undefined

Literal values

  • false
  • true

Default value details

Declaration
false

Source: packages/ui/src/components/tree-view/TreeViewNode.vue

Resolved value
false

Source

TreeViewNode.vue:24

packages/ui/src/components/tree-view/TreeViewNode.vue

TreeViewNode — Events
NameSignature or typeDescription
@select
[node: TreeNode<unknown>]
Emits the full node data when this node is activated or selected.
Details

Declared type

[node: TreeNode<unknown>]

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Source

TreeViewNode.vue

packages/ui/src/components/tree-view/TreeViewNode.vue

@toggle
[id: string]
Emits this node id when its expanded state should toggle.
Details

Declared type

[id: string]

Source

TreeViewNode.vue

packages/ui/src/components/tree-view/TreeViewNode.vue

@check
[node: TreeNode<unknown>]
Emits this node when its checkbox state should toggle.
Details

Declared type

[node: TreeNode<unknown>]

Referenced types

TreeNode
Type definition — TreeNode
export interface TreeNode<T = unknown> {
    /** 节点唯一标识 */
    id: string
    /** 节点显示文本 */
    label: string
    /** 节点图标名称或自定义图标类名 */
    icon?: string
    /** 子节点列表 */
    children?: TreeNode<T>[]
    /** 自定义业务数据 */
    data?: T
    /** 是否禁用交互 */
    disabled?: boolean
    /** 是否叶子节点（懒加载时若为 true 则不展示展开图标） */
    isLeaf?: boolean
    /** 懒加载子节点是否已加载 */
    loaded?: boolean
    /** 懒加载是否处于请求中 */
    loading?: boolean
    /** 过滤搜索时是否隐藏 */
    hidden?: boolean
}

Source

TreeViewNode.vue

packages/ui/src/components/tree-view/TreeViewNode.vue

@focus-prev
[]
Requests moving focus to the previous visible tree node.
Details

Declared type

[]

Source

TreeViewNode.vue

packages/ui/src/components/tree-view/TreeViewNode.vue

@focus-next
[]
Requests moving focus to the next visible tree node.
Details

Declared type

[]

Source

TreeViewNode.vue

packages/ui/src/components/tree-view/TreeViewNode.vue

@focus-parent
[]
Requests moving focus to the parent node.
Details

Declared type

[]

Source

TreeViewNode.vue

packages/ui/src/components/tree-view/TreeViewNode.vue

@focus-first-child
[]
Requests moving focus to the first child when the node is expanded.
Details

Declared type

[]

Source

TreeViewNode.vue

packages/ui/src/components/tree-view/TreeViewNode.vue

@focus-first
[]
Requests moving focus to the first visible node in the tree.
Details

Declared type

[]

Source

TreeViewNode.vue

packages/ui/src/components/tree-view/TreeViewNode.vue

@focus-last
[]
Requests moving focus to the last visible node in the tree.
Details

Declared type

[]

Source

TreeViewNode.vue

packages/ui/src/components/tree-view/TreeViewNode.vue

TreeViewNode — Exposes
NameSignature or typeDescription
focus
() => void
Moves focus to the tree item element for this node.
Details

Declared type

() => void

Source

TreeViewNode.vue:276

packages/ui/src/components/tree-view/TreeViewNode.vue

nodeId
string
The id of the node represented by this row.
Details

Declared type

string

Source

TreeViewNode.vue:276

packages/ui/src/components/tree-view/TreeViewNode.vue

Accessibility ​

  • Keyboard Operation: Follows WAI-ARIA TreeView role specification
KeyDescription
ArrowUpFocus the previous visible node
ArrowDownFocus the next visible node
ArrowRightExpand the node if collapsed; if already expanded, focus the first child node
ArrowLeftCollapse the node if expanded; if already collapsed, focus the parent node
Enter / SpaceSelect the node (single mode) or toggle check state (checkbox mode)
HomeFocus the first node
EndFocus the last node
  • ARIA Attributes: Uses role="tree" and role="treeitem" semantic markup; checkbox mode uses aria-checked attribute (true / false / mixed)
  • Focus Management: Uses roving tabindex for focus management

Drag and Drop Sorting ​

Enable draggable to allow nodes to be dragged and reordered. Use allowDrag and allowDrop to finely control drag behavior. When v-model:nodes is enabled, the component automatically reorders tree data on drop; otherwise, handle the node-drop event manually.

vue
<script setup>
import { ref } from 'vue'
import { TreeView, moveNode } from 'brutx-ui-vue'
import type { TreeNode } from 'brutx-ui-vue'

const nodes = ref<TreeNode[]>([
    {
        id: 'src',
        label: 'src',
        children: [
            { id: 'button', label: 'Button.vue' },
            { id: 'input', label: 'Input.vue' },
        ],
    },
    { id: 'pkg', label: 'package.json' },
])

function handleDrop(event: DragEvent, node: TreeNode, dropType: 'before' | 'after' | 'inner') {
    // If v-model:nodes is not used, call moveNode manually to reorder
    // nodes.value = moveNode(nodes.value, draggedNode, node, dropType)
}
</script>

<template>
    <TreeView
        v-model:nodes="nodes"
        :nodes="nodes"
        draggable
        :allow-drag="(node) => node.id !== 'pkg'"
        @node-drop="handleDrop"
    />
</template>

Utility Function:

ts
import { moveNode } from 'brutx-ui-vue'

// Pure function for manually reordering tree data
const newNodes = moveNode(nodes, draggedNode, targetNode, 'before')

Lazy Loading ​

Enable lazy and provide a load function to automatically load children asynchronously when expanding unloaded nodes. The component uses loadingKeys internally to prevent concurrent requests and marks the loaded state upon completion.

vue
<script setup>
import { TreeView } from 'brutx-ui-vue'
import type { TreeNode } from 'brutx-ui-vue'

const nodes: TreeNode[] = [
    { id: 'root', label: 'Root', isLeaf: false },
]

async function loadChildren(node: TreeNode): Promise<TreeNode[]> {
    const response = await fetch(`/api/children/${node.id}`)
    return response.json()
}
</script>

<template>
    <TreeView
        :nodes="nodes"
        lazy
        :load="loadChildren"
        retry-on-error
    />
</template>

TreeNode Lazy Loading Fields:

FieldTypeDescription
isLeafbooleanWhether the node is a leaf; used in lazy mode to determine if expandable
loadedbooleanWhether children have been loaded
loadingbooleanWhether children are currently loading

Node Filtering ​

Enable filterable and use the component instance's filter method to trigger filtering. Filtering recursively computes match state -- matched nodes and their ancestors are shown, the rest are hidden, and parent nodes of matched nodes are automatically expanded.

vue
<script setup>
import { ref } from 'vue'
import { TreeView } from 'brutx-ui-vue'
import type { TreeNode } from 'brutx-ui-vue'

const treeRef = ref()
const query = ref('')

const nodes: TreeNode[] = [
    {
        id: 'src',
        label: 'src',
        children: [
            { id: 'button', label: 'Button.vue' },
            { id: 'input', label: 'Input.vue' },
        ],
    },
    { id: 'pkg', label: 'package.json' },
]

function handleSearch() {
    treeRef.value?.filter(query.value)
}
</script>

<template>
    <div>
        <input v-model="query" @input="handleSearch" placeholder="Search nodes..." />
        <TreeView
            ref="treeRef"
            :nodes="nodes"
            filterable
            :default-expanded="['src']"
        />
    </div>
</template>

Reload Node ​

Use the component instance's reloadNode method to reset a node's loaded state and re-trigger lazy loading. Useful for refreshing child node data.

vue
<script setup>
import { ref } from 'vue'
import { TreeView } from 'brutx-ui-vue'
import type { TreeNode } from 'brutx-ui-vue'

const treeRef = ref()

function refreshNode(nodeKey: string) {
    treeRef.value?.reloadNode(nodeKey)
}
</script>

<template>
    <TreeView
        ref="treeRef"
        :nodes="nodes"
        lazy
        :load="loadChildren"
    />
    <button @click="refreshNode('src')">Reload src Node</button>
</template>

FAQ ​

Q: In checkbox mode, why does the parent node become indeterminate?

A: This is by design with cascading selection. When only some of a parent node's children are checked, the parent displays an indeterminate state (aria-checked="mixed"), indicating "partially selected". The parent only shows as fully checked when all children are checked. Conversely, checking a parent automatically checks all its descendants.

Q: How do I expand specific nodes on initial load?

A: Use the defaultExpanded prop to pass an array of node id values that should be initially expanded. For example, :default-expanded="['src', 'components']" will automatically expand those nodes when the component loads. Subsequent expand/collapse operations will trigger the update:expanded event.

Q: What happens to disabled nodes in checkbox mode?

A: Nodes with disabled: true cannot be checked in checkbox mode, and their checkbox will display as disabled. If a parent node is disabled, its children can still be independently checked. Disabled nodes do not affect click-to-select behavior in single mode (single mode does not use the disabled property).

Brute force builds.

© 2026 BrutxUI · MIT License