Tree
A hierarchical tree component with drag-and-drop functionality for file systems and nested data structures.
Overview
The Tree component provides a powerful hierarchical data structure with drag-and-drop functionality, perfect for file explorers, nested menus, and complex data organization.
API Reference
Tree
The main container component that manages the tree structure and provides droppable functionality for tree nodes.
Props
Name | Type | Default | Description |
---|---|---|---|
data | T[] | Required | Array of tree data items |
itemKey | TValidItemKeys<T> | Required | Key to use as unique identifier for items |
nestingKey | TValidNestingKeys<T> | Required | Key that contains child items array |
groups | string[] | ['tree'] | Groups for drag-n-drop operations |
Slots
Name | Props | Description |
---|---|---|
default | { item } | Content for each tree item |
TreeItem
Component for displaying individual tree nodes with drag functionality and expand/collapse behavior.
Props
Name | Type | Default | Description |
---|---|---|---|
data | T | Required | Tree item data |
itemKey | TValidItemKeys<T> | Required | Key to use as unique identifier |
nestingKey | TValidNestingKeys<T> | Required | Key that contains child items array |
source | T[] | Required | Array of all items at current level |
index | number | Required | Index of the item in the source array |
groups | string[] | Required | Groups for drag-n-drop operations |
Slots
Name | Props | Description |
---|---|---|
default | { item } | Content for the tree item |
TreeControls
Component for managing tree operations like expand all, collapse all, etc.
Props
Name | Type | Default | Description |
---|---|---|---|
expanded | boolean | false | Whether the tree node is expanded |
hasChildren | boolean | false | Whether the item has children |
onArrowClick | () => void | Required | Callback for arrow click events |
onDragStart | (event: PointerEvent) => void | Required | Callback for drag start events |
Slots
No slots available in this component. TreeControls renders arrow and drag handle controls.
TreeArrow
Component for displaying expand/collapse arrows with custom styling.
Props
Name | Type | Default | Description |
---|---|---|---|
expanded | boolean | false | Whether the arrow should be rotated |
Slots
No slots available in this component. TreeArrow renders an arrow icon.
TreeDragHandle
Component for providing a dedicated drag handle for tree items.
Props
No props available. This component provides a drag handle with predefined styling.
Slots
No slots available in this component. TreeDragHandle renders a drag handle icon.
Types
export type TValidItemKeys<T> = {
[K in keyof T]-?: T[K] extends string | number ? K : never;
}[keyof T];
export type TValidNestingKeys<T> = {
[K in keyof T]: T[K] extends T[] | undefined ? K : never;
}[keyof T];
Installation
pnpm dlx @vue-dnd-kit/components add tree
Import
import {
Tree,
TreeItem,
TreeControls,
TreeArrow,
TreeDragHandle,
} from '{your component path}/Tree';
Usage
Basic Example
<script setup lang="ts">
import { ref } from 'vue';
import { Tree } from '{your component path}/Tree';
interface IUser {
id: number;
name: string;
children?: IUser[];
}
const users = ref<IUser[]>([
{
id: 1,
name: 'John',
children: [
{
id: 2,
name: 'Victoria',
children: [],
},
{
id: 3,
name: 'Abraham',
children: [
{
id: 4,
name: 'Eliz',
},
],
},
],
},
{
id: 5,
name: 'Sarah',
children: [
{
id: 6,
name: 'Michael',
},
],
},
]);
</script>
<template>
<Tree
:data="users"
item-key="id"
nesting-key="children"
v-slot="{ item }"
>
<div class="tree-item-content">
<span class="user-name">{{ item.name }}</span>
<span class="user-id">#{{ item.id }}</span>
</div>
</Tree>
</template>
<style scoped>
.tree-item-content {
display: flex;
align-items: center;
gap: 8px;
}
.user-name {
font-weight: 500;
}
.user-id {
color: #6b7280;
font-size: 0.875rem;
}
</style>
Features
- Hierarchical structure: Support for nested tree nodes with unlimited depth
- Drag and drop: Move nodes within the tree structure
- Expandable/collapsible: Built-in expand/collapse functionality for tree nodes
- Visual indicators: Indicators for items with and without children
- Customizable controls: Customizable drag handles and arrow controls
- Modern styling: Hover effects and smooth animations
- Empty zone highlighting: Visual feedback for drop targets
Styling
The Tree component comes with a set of predefined CSS classes:
.tree-container
- Main tree container.tree-item
- Individual tree item.tree-item-content
- Content wrapper for tree items.tree-children
- Container for child items.tree-children-empty
- Styling for empty child containers.tree-children-overed
- Applied when hovering over drop zone.tree-container-overed
- Applied when hovering over main container.tree-item-text
- Text content within tree items.tree-controls
- Container for arrow and drag handle.tree-arrow
- Arrow control styling.tree-drag-handle
- Drag handle styling.tree-item-dot
- Dot indicator for items without children
For status styling, you can use:
.tree-item.dragging
- Applied when an item is being dragged.tree-item.drag-over
- Applied when dragging over an item
Events
Tree components handle various drag-and-drop events:
onStart
: When dragging a node startsonMove
: When a node is being movedonHover
: When hovering over a drop zoneonLeave
: When leaving a drop zoneonEnd
: When dragging endsonExpand
: When a node is expandedonCollapse
: When a node is collapsed
Performance
The component is optimized for large trees:
- Efficient re-rendering during drag operations
- Minimal DOM updates
- Virtual scrolling support for large datasets
- Smooth animations using CSS transforms
Important Notes
- Each node must have a unique identifier specified by
itemKey
- Use appropriate
nestingKey
for child items - Implement proper data persistence for tree structure changes
- Consider using
TransitionGroup
for smooth node animations - Handle empty trees appropriately in your UI
- Use appropriate indentation for nested levels
- Implement proper validation for drag operations (e.g., preventing dropping a parent into its child)
Related Components
TreeItem
Component for displaying individual tree nodes with drag functionality.
TreeControls
Component for displaying tree node controls (arrow and drag handle).
TreeArrow
Component for displaying expand/collapse arrows.
TreeDragHandle
Component for displaying drag handles.
This component is part of the @vue-dnd-kit/components library, which provides a CLI that generates components directly into your project directory, similar to shadcn.