Skip to content

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.

📁
Documents
📁
Work
📁
Project A
📁
Project B
📄
report.pdf
📁
Personal
📁
Photos
📁
Videos
📄
notes.txt
📄
presentation.pptx
📁
Downloads
📄
setup.exe
📄
document.docx
📁
Pictures
📁
Screenshots
📁
Wallpapers

API Reference

Tree

The main container component that manages the tree structure and provides droppable functionality for tree nodes.

Props

NameTypeDefaultDescription
dataT[]RequiredArray of tree data items
itemKeyTValidItemKeys<T>RequiredKey to use as unique identifier for items
nestingKeyTValidNestingKeys<T>RequiredKey that contains child items array
groupsstring[]['tree']Groups for drag-n-drop operations

Slots

NamePropsDescription
default{ item }Content for each tree item

TreeItem

Component for displaying individual tree nodes with drag functionality and expand/collapse behavior.

Props

NameTypeDefaultDescription
dataTRequiredTree item data
itemKeyTValidItemKeys<T>RequiredKey to use as unique identifier
nestingKeyTValidNestingKeys<T>RequiredKey that contains child items array
sourceT[]RequiredArray of all items at current level
indexnumberRequiredIndex of the item in the source array
groupsstring[]RequiredGroups for drag-n-drop operations

Slots

NamePropsDescription
default{ item }Content for the tree item

TreeControls

Component for managing tree operations like expand all, collapse all, etc.

Props

NameTypeDefaultDescription
expandedbooleanfalseWhether the tree node is expanded
hasChildrenbooleanfalseWhether the item has children
onArrowClick() => voidRequiredCallback for arrow click events
onDragStart(event: PointerEvent) => voidRequiredCallback 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

NameTypeDefaultDescription
expandedbooleanfalseWhether 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

typescript
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

bash
pnpm dlx @vue-dnd-kit/components add tree

Import

ts
import {
  Tree,
  TreeItem,
  TreeControls,
  TreeArrow,
  TreeDragHandle,
} from '{your component path}/Tree';

Usage

Basic Example

vue
<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 starts
  • onMove: When a node is being moved
  • onHover: When hovering over a drop zone
  • onLeave: When leaving a drop zone
  • onEnd: When dragging ends
  • onExpand: When a node is expanded
  • onCollapse: 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

  1. Each node must have a unique identifier specified by itemKey
  2. Use appropriate nestingKey for child items
  3. Implement proper data persistence for tree structure changes
  4. Consider using TransitionGroup for smooth node animations
  5. Handle empty trees appropriately in your UI
  6. Use appropriate indentation for nested levels
  7. Implement proper validation for drag operations (e.g., preventing dropping a parent into its child)

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.

Released under the MIT License.