Tree

A tree component for browsing folders and files with virtualization.

vu-tree · @velkin/react-pro/tree

Copy page

Import

React

npm i @velkin/react-pro

import { LicenseInfo } from "@velkin/license";
// Vite: import.meta.env.VITE_VELKIN_LICENSE_KEY
// Next: process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY
LicenseInfo.setLicenseKey(import.meta.env.VITE_VELKIN_LICENSE_KEY ?? process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY ?? "");

// @velkin-pro
import { VuTree } from "@velkin/react-pro/tree";

Examples

API

Props

Prop	Type	Default	Description
items	VuTreeItem[]	[]	Directory data with unique `id` and `label`. Default: `[]`.
value	`null \| string`	null	Currently open file id. Default: `null`.
expandedIds	`string[]`	—	Controlled expanded folder ids; omit for uncontrolled `item.expanded`.
filterText	`string`	""	Case-insensitive label filter. Default: `""`.
noResultsLabel	`string`	""	Fallback when filter matches no rows; defaults to a localized label.
filterDebounceMs	`number`	150	Delay before applying `filterText` to large trees. Default: `150`.
expandIcon	`"ion:chevron-down"`	"ion:chevron-down"	Iconify name for expanded folders. Default: chevron-down.
collapseIcon	`"ion:chevron-forward"`	"ion:chevron-forward"	Iconify name for collapsed folders. Default: chevron-forward.
size	VuTreeSize	"md"	Row density preset. Default: `"md"`.
itemHeight	`number`	—	Virtual row height in px; defaults to the `size` preset (sm 28, md 32, lg 36).
variant	VuTreeVariant	"explorer"	`explorer` borderless sidebar or `panel` card. Default: `"explorer"`.
withIcons	`boolean`	true	Auto file/folder icons when nodes omit `icon`. Default: `true`.
withLines	`boolean`	false	Show guide lines between nodes. Default: `false`.
showSize	`boolean`	true	Show trailing file size when nodes include `size`. Default: `true`.
withFolderFirstSort	`boolean`	false	Sort folders before files at each level. Default: `false`.
autoExpandParent	`boolean`	true	Expand ancestors while filtering. Default: `true`.
itemDrag	VuTreeDragMode	"off"	Row drag mode: `off`, `reorder`, `reparent`, or `both`. Default: `"off"`.
lazyLoad	VuTreeLazyLoadFn	—	Async children fetch when a folder expands.

Events

Event	Detail	Description
vu-activate	VuTreeActivateDetail	When a file row is activated.
vu-expand	VuTreeExpandDetail	When a folder row expands.
vu-collapse	VuTreeCollapseDetail	When a folder row collapses.
vu-contextmenu	VuTreeContextMenuDetail	When a row receives `contextmenu`.
vu-dragstart	VuTreeDragStartDetail	When a row drag starts.
vu-reorder	VuTreeReorderDetail	When a row is reordered among siblings.
vu-move	VuTreeMoveDetail	When a row is reparented or dropped into a folder.

Slots

Slot	Description
—	- Default slot for additional tree content.
no-results	Custom body when `filterText` matches no rows.

CSS parts

Part	Description
tree	The outer scrolling tree wrapper.
item-wrapper	Wrapper for each virtualized row.
item	Clickable row container for a node.
indent	Indent gutter grouping ancestor guide columns.
indent-guide	One ancestor-depth vertical guide column.
switcher	Chevron column on expandable folder rows; omitted on file rows when `withlines`.
content	Label column between icon and trailing meta.
item-label	Text label of a node.
trailing	Fixed-width trailing column (badge + file size).
item-size	File size text inside the trailing column.
item-badge	Git-style status badge before file size.
item-icon-left	Leading file/folder icon.
expand-button	Expand/collapse chevron or loading spinner.
no-results	Filter empty-state region.
no-results-label	Default no-results text when the slot is empty.
drop-indicator	Insertion line or folder highlight shown during row drag.

Methods

Method	Description
expandAll	Expands all folders.
collapseAll	Collapses all folders.
focusNode	Focuses a visible node by flattened index.
scrollToItem	Scrolls a visible node into view by id.
focusItemById	Moves roving focus and scrolls a visible node into view.

Types

Name	Definition
string \| null	`null \| string`
VuTreeActivateDetail	`{ item: VuTreeItem; value: string; }`
VuTreeCollapseDetail	`{ item: VuTreeItem; value: string; }`
VuTreeContextMenuDetail	`{ item: VuTreeItem; value: string; originalEvent: MouseEvent; }`
VuTreeDragMode	`"both" \| "off" \| "reorder" \| "reparent"`
VuTreeDragStartDetail	`{ item: VuTreeItem; value: string; }`
VuTreeExpandDetail	`{ item: VuTreeItem; value: string; }`
VuTreeLazyLoadFn	`(item: VuTreeItem) => Promise<VuTreeItem[]>`
VuTreeMoveDetail	`{ item: VuTreeItem; value: string; fromParentId: string \| null; toParentId: string \| null; fromIndex: number; toIndex: number; position: VuTreeDropPosition; }`
VuTreeReorderDetail	`{ item: VuTreeItem; value: string; parentId: string \| null; fromIndex: number; toIndex: number; position: "before" \| "after"; }`
VuTreeSize	`"sm" \| "md" \| "lg"`
VuTreeVariant	`"explorer" \| "panel"`

Import

React

npm i @velkin/react-pro import { LicenseInfo } from "@velkin/license"; // Vite: import.meta.env.VITE_VELKIN_LICENSE_KEY // Next: process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY LicenseInfo.setLicenseKey(import.meta.env.VITE_VELKIN_LICENSE_KEY ?? process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY ?? ""); // @velkin-pro import { VuTree } from "@velkin/react-pro/tree";

API

Props

Prop	Type	Default	Description
items	VuTreeItem[]	[]	Directory data with unique `id` and `label`. Default: `[]`.
value	`null \| string`	null	Currently open file id. Default: `null`.
expandedIds	`string[]`	—	Controlled expanded folder ids; omit for uncontrolled `item.expanded`.
filterText	`string`	""	Case-insensitive label filter. Default: `""`.
noResultsLabel	`string`	""	Fallback when filter matches no rows; defaults to a localized label.
filterDebounceMs	`number`	150	Delay before applying `filterText` to large trees. Default: `150`.
expandIcon	`"ion:chevron-down"`	"ion:chevron-down"	Iconify name for expanded folders. Default: chevron-down.
collapseIcon	`"ion:chevron-forward"`	"ion:chevron-forward"	Iconify name for collapsed folders. Default: chevron-forward.
size	VuTreeSize	"md"	Row density preset. Default: `"md"`.
itemHeight	`number`	—	Virtual row height in px; defaults to the `size` preset (sm 28, md 32, lg 36).
variant	VuTreeVariant	"explorer"	`explorer` borderless sidebar or `panel` card. Default: `"explorer"`.
withIcons	`boolean`	true	Auto file/folder icons when nodes omit `icon`. Default: `true`.
withLines	`boolean`	false	Show guide lines between nodes. Default: `false`.
showSize	`boolean`	true	Show trailing file size when nodes include `size`. Default: `true`.
withFolderFirstSort	`boolean`	false	Sort folders before files at each level. Default: `false`.
autoExpandParent	`boolean`	true	Expand ancestors while filtering. Default: `true`.
itemDrag	VuTreeDragMode	"off"	Row drag mode: `off`, `reorder`, `reparent`, or `both`. Default: `"off"`.
lazyLoad	VuTreeLazyLoadFn	—	Async children fetch when a folder expands.

Events

Event	Detail	Description
vu-activate	VuTreeActivateDetail	When a file row is activated.
vu-expand	VuTreeExpandDetail	When a folder row expands.
vu-collapse	VuTreeCollapseDetail	When a folder row collapses.
vu-contextmenu	VuTreeContextMenuDetail	When a row receives `contextmenu`.
vu-dragstart	VuTreeDragStartDetail	When a row drag starts.
vu-reorder	VuTreeReorderDetail	When a row is reordered among siblings.
vu-move	VuTreeMoveDetail	When a row is reparented or dropped into a folder.

Slots

Slot	Description
—	- Default slot for additional tree content.
no-results	Custom body when `filterText` matches no rows.

CSS parts

Part	Description
tree	The outer scrolling tree wrapper.
item-wrapper	Wrapper for each virtualized row.
item	Clickable row container for a node.
indent	Indent gutter grouping ancestor guide columns.
indent-guide	One ancestor-depth vertical guide column.
switcher	Chevron column on expandable folder rows; omitted on file rows when `withlines`.
content	Label column between icon and trailing meta.
item-label	Text label of a node.
trailing	Fixed-width trailing column (badge + file size).
item-size	File size text inside the trailing column.
item-badge	Git-style status badge before file size.
item-icon-left	Leading file/folder icon.
expand-button	Expand/collapse chevron or loading spinner.
no-results	Filter empty-state region.
no-results-label	Default no-results text when the slot is empty.
drop-indicator	Insertion line or folder highlight shown during row drag.

Methods

Method	Description
expandAll	Expands all folders.
collapseAll	Collapses all folders.
focusNode	Focuses a visible node by flattened index.
scrollToItem	Scrolls a visible node into view by id.
focusItemById	Moves roving focus and scrolls a visible node into view.

Types

Name	Definition
string \| null	`null \| string`
VuTreeActivateDetail	`{ item: VuTreeItem; value: string; }`
VuTreeCollapseDetail	`{ item: VuTreeItem; value: string; }`
VuTreeContextMenuDetail	`{ item: VuTreeItem; value: string; originalEvent: MouseEvent; }`
VuTreeDragMode	`"both" \| "off" \| "reorder" \| "reparent"`
VuTreeDragStartDetail	`{ item: VuTreeItem; value: string; }`
VuTreeExpandDetail	`{ item: VuTreeItem; value: string; }`
VuTreeLazyLoadFn	`(item: VuTreeItem) => Promise<VuTreeItem[]>`
VuTreeMoveDetail	`{ item: VuTreeItem; value: string; fromParentId: string \| null; toParentId: string \| null; fromIndex: number; toIndex: number; position: VuTreeDropPosition; }`
VuTreeReorderDetail	`{ item: VuTreeItem; value: string; parentId: string \| null; fromIndex: number; toIndex: number; position: "before" \| "after"; }`
VuTreeSize	`"sm" \| "md" \| "lg"`
VuTreeVariant	`"explorer" \| "panel"`

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Data display

Guides

Browse

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Data display

Guides

Browse