Tree View Components

Interactive hierarchical tree structures for displaying files, folders, and nested data. Perfect for file explorers, navigation menus, and organizational charts.

Installation

1. Stimulus Controller Setup

Start by adding the following controller to your project:

import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  static targets = ["icon", "content"];
  static values = {
    animate: { type: Boolean, default: true }, // Whether to animate the tree view
  };

  connect() {
    this.isAnimating = false;
    // Initialize any folders that should start open
    this.element.querySelectorAll('[data-state="open"]').forEach((el) => {
      const button = el.previousElementSibling;
      if (button) {
        const icon = button.querySelector('[data-tree-view-target="icon"]');
        if (icon) {
          icon.classList.add("folder-open");
          icon.innerHTML = this.openFolderSvg;
        }
      }
    });

    this.addKeyboardListeners();
  }

  disconnect() {
    // Clean up any remaining event listeners
    if (this.onTransitionEndBound) {
      this.element.querySelectorAll('[data-tree-view-target="content"]').forEach((content) => {
        content.removeEventListener("transitionend", this.onTransitionEndBound);
      });
    }
    this.element.removeEventListener("keydown", this.handleKeydownBound);
  }

  addKeyboardListeners() {
    this.handleKeydownBound = this.handleKeydown.bind(this);
    this.element.addEventListener("keydown", this.handleKeydownBound);
  }

  handleKeydown(event) {
    const triggers = Array.from(this.element.querySelectorAll('button[data-action="click->tree-view#toggle"]'));
    const currentIndex = triggers.indexOf(document.activeElement);
    if (currentIndex === -1) return;

    switch (event.key) {
      case "ArrowUp":
        event.preventDefault();
        let prevIndex = currentIndex;
        do {
          prevIndex = (prevIndex - 1 + triggers.length) % triggers.length;
        } while (prevIndex !== currentIndex && this.isElementHidden(triggers[prevIndex]));
        triggers[prevIndex].focus();
        break;
      case "ArrowDown":
        event.preventDefault();
        let nextIndex = currentIndex;
        do {
          nextIndex = (nextIndex + 1) % triggers.length;
        } while (nextIndex !== currentIndex && this.isElementHidden(triggers[nextIndex]));
        triggers[nextIndex].focus();
        break;
      case "Enter":
      case " ":
        event.preventDefault();
        triggers[currentIndex].click();
        break;
    }
  }

  isElementHidden(element) {
    let current = element;
    while (current && current !== this.element) {
      if (current.hasAttribute("hidden") || current.classList.contains("hidden")) {
        return true;
      }
      current = current.parentElement;
    }
    return false;
  }

  toggle(event) {
    const button = event.currentTarget;
    const content = document.getElementById(button.getAttribute("aria-controls"));
    const icon = button.querySelector('[data-tree-view-target="icon"]');

    // Prevent multiple animations from running simultaneously
    if (this.isAnimating) return;

    const isOpen = button.getAttribute("aria-expanded") === "true";

    // Toggle aria attributes
    button.setAttribute("aria-expanded", !isOpen);
    content.setAttribute("data-state", isOpen ? "closed" : "open");

    if (this.animateValue) {
      this.isAnimating = true;

      // Remove any existing transition listeners
      content.removeEventListener("transitionend", this.onTransitionEndBound);
      this.onTransitionEndBound = () => {
        if (isOpen) {
          content.setAttribute("hidden", "");
        }
        content.style.height = "";
        content.style.transition = "";
        content.removeEventListener("transitionend", this.onTransitionEndBound);
        this.isAnimating = false;
      };
      content.addEventListener("transitionend", this.onTransitionEndBound);

      if (isOpen) {
        // Closing animation
        const height = content.scrollHeight;
        content.style.height = height + "px";
        // Force a reflow
        content.offsetHeight;
        content.style.transition = "height 300ms ease-out";
        content.style.height = "0";
      } else {
        // Opening animation
        content.removeAttribute("hidden");
        content.style.height = "0";
        // Force a reflow
        content.offsetHeight;
        content.style.transition = "height 300ms ease-out";
        const height = content.scrollHeight;
        content.style.height = height + "px";
      }
    } else {
      // No animation - just toggle visibility
      if (isOpen) {
        content.setAttribute("hidden", "");
      } else {
        content.removeAttribute("hidden");
      }
    }

    // Update icons
    if (isOpen) {
      icon.classList.remove("folder-open");
      icon.innerHTML = this.closedFolderSvg;
    } else {
      icon.classList.add("folder-open");
      icon.innerHTML = this.openFolderSvg;
    }

    // Update button state
    button.setAttribute("data-state", isOpen ? "closed" : "open");
  }

  get openFolderSvg() {
    return `<g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor">
      <path d="M5,14.75h-.75c-1.105,0-2-.895-2-2V4.75c0-1.105,.895-2,2-2h1.825c.587,0,1.144,.258,1.524,.705l1.524,1.795h4.626c1.105,0,2,.895,2,2v1"></path>
      <path d="M16.148,13.27l.843-3.13c.257-.953-.461-1.89-1.448-1.89H6.15c-.678,0-1.272,.455-1.448,1.11l-.942,3.5c-.257,.953,.461,1.89,1.448,1.89H14.217c.904,0,1.696-.607,1.931-1.48Z"></path>
    </g>`;
  }

  get closedFolderSvg() {
    return `<g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor">
      <path d="M13.75,5.25c1.105,0,2,.895,2,2v5.5c0,1.105-.895,2-2,2H4.25c-1.105,0-2-.895-2-2V4.75c0-1.105,.895-2,2-2h1.825c.587,0,1.144,.258,1.524,.705l1.524,1.795h4.626Z"></path>
    </g>`;
  }
}

Examples

Basic Tree View

A hierarchical file and folder structure with collapsible directories and smooth animations.

page.tsx

header.tsx

footer.tsx

utils.ts

<div data-controller="tree-view" data-tree-view-animate-value="true" class="h-[400px] w-full p-4 rounded-lg border border-neutral-200 dark:border-neutral-700 bg-white dark:bg-neutral-800">
  <!-- Root folder "src" -->
  <div class="overflow-hidden">
    <button type="button"
            data-action="click->tree-view#toggle"
            aria-controls="tree-content-src"
            aria-expanded="true"
            data-state="open"
            class="flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm hover:bg-neutral-100 dark:hover:bg-neutral-700 transition-colors duration-150 outline-none focus:underline">
      <svg data-tree-view-target="icon" class="folder-open" xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M5,14.75h-.75c-1.105,0-2-.895-2-2V4.75c0-1.105,.895-2,2-2h1.825c.587,0,1.144,.258,1.524,.705l1.524,1.795h4.626c1.105,0,2,.895,2,2v1"></path><path d="M16.148,13.27l.843-3.13c.257-.953-.461-1.89-1.448-1.89H6.15c-.678,0-1.272,.455-1.448,1.11l-.942,3.5c-.257,.953,.461,1.89,1.448,1.89H14.217c.904,0,1.696-.607,1.931-1.48Z"></path></g></svg>

      <span class="font-medium">src</span>
    </button>
    <div id="tree-content-src"
         data-state="open"
         role="region"
         class="ml-4 pl-2 border-l border-neutral-200 dark:border-neutral-700 space-y-1 overflow-hidden transition-[height]"
         data-tree-view-target="content">
      <!-- Folder "app" -->
      <div class="overflow-hidden">
        <button type="button"
                data-action="click->tree-view#toggle"
                aria-controls="tree-content-app"
                aria-expanded="true"
                data-state="open"
                class="flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm hover:bg-neutral-100 dark:hover:bg-neutral-700 transition-colors duration-150 outline-none focus:underline">
          <svg data-tree-view-target="icon" class="folder-open" xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M5,14.75h-.75c-1.105,0-2-.895-2-2V4.75c0-1.105,.895-2,2-2h1.825c.587,0,1.144,.258,1.524,.705l1.524,1.795h4.626c1.105,0,2,.895,2,2v1"></path><path d="M16.148,13.27l.843-3.13c.257-.953-.461-1.89-1.448-1.89H6.15c-.678,0-1.272,.455-1.448,1.11l-.942,3.5c-.257,.953,.461,1.89,1.448,1.89H14.217c.904,0,1.696-.607,1.931-1.48Z"></path></g></svg>
          <span class="font-medium">app</span>
        </button>
        <div id="tree-content-app"
             data-state="open"
             role="region"
             class="ml-4 pl-2 border-l border-neutral-200 dark:border-neutral-700 space-y-1 overflow-hidden transition-[height]"
             data-tree-view-target="content">
          <!-- File items in app -->
          <button type="button" data-tree-view-item class="flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm text-neutral-600 dark:text-neutral-300 hover:bg-neutral-100 dark:hover:bg-neutral-700 transition-colors duration-150 outline-none focus:underline">
            <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M15.16,6.25h-3.41c-.552,0-1-.448-1-1V1.852"></path><path d="M2.75,14.25V3.75c0-1.105,.895-2,2-2h5.586c.265,0,.52,.105,.707,.293l3.914,3.914c.188,.188,.293,.442,.293,.707v7.586c0,1.105-.895,2-2,2H4.75c-1.105,0-2-.895-2-2Z"></path></g></svg>
            <span>layout.tsx</span>
          </button>
          <div class="flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm text-neutral-600 dark:text-neutral-300 hover:bg-neutral-100 dark:hover:bg-neutral-700 transition-colors duration-150 outline-none focus:underline">
            <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M15.16,6.25h-3.41c-.552,0-1-.448-1-1V1.852"></path><path d="M2.75,14.25V3.75c0-1.105,.895-2,2-2h5.586c.265,0,.52,.105,.707,.293l3.914,3.914c.188,.188,.293,.442,.293,.707v7.586c0,1.105-.895,2-2,2H4.75c-1.105,0-2-.895-2-2Z"></path></g></svg>
            <span>page.tsx</span>
          </div>
          <!-- Folder "components" -->
          <div class="overflow-hidden">
            <button type="button"
                    data-action="click->tree-view#toggle"
                    aria-controls="tree-content-components"
                    aria-expanded="true"
                    data-state="open"
                    class="flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm hover:bg-neutral-100 dark:hover:bg-neutral-700 transition-colors duration-150 outline-none focus:underline">
              <svg data-tree-view-target="icon" class="folder-open" xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M5,14.75h-.75c-1.105,0-2-.895-2-2V4.75c0-1.105,.895-2,2-2h1.825c.587,0,1.144,.258,1.524,.705l1.524,1.795h4.626c1.105,0,2,.895,2,2v1"></path><path d="M16.148,13.27l.843-3.13c.257-.953-.461-1.89-1.448-1.89H6.15c-.678,0-1.272,.455-1.448,1.11l-.942,3.5c-.257,.953,.461,1.89,1.448,1.89H14.217c.904,0,1.696-.607,1.931-1.48Z"></path></g></svg>
              <span class="font-medium">components</span>
            </button>
            <div id="tree-content-components"
                 data-state="open"
                 role="region"
                 class="ml-4 pl-2 border-l border-neutral-200 dark:border-neutral-700 space-y-1 overflow-hidden transition-[height]"
                 data-tree-view-target="content">
              <!-- Folder "ui" -->
              <div class="overflow-hidden">
                <button type="button"
                        data-action="click->tree-view#toggle"
                        aria-controls="tree-content-ui"
                        aria-expanded="false"
                        data-state="closed"
                        class="flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm hover:bg-neutral-100 dark:hover:bg-neutral-700 transition-colors duration-150 outline-none focus:underline">
                  <svg data-tree-view-target="icon" class="folder-closed" xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M13.75,5.25c1.105,0,2,.895,2,2v5.5c0,1.105-.895,2-2,2H4.25c-1.105,0-2-.895-2-2V4.75c0-1.105,.895-2,2-2h1.825c.587,0,1.144,.258,1.524,.705l1.524,1.795h4.626Z"></path></g></svg>
                  <span class="font-medium">ui</span>
                </button>
                <div id="tree-content-ui"
                     data-state="closed"
                     role="region"
                     class="ml-4 pl-2 border-l border-neutral-200 dark:border-neutral-700 space-y-1 overflow-hidden transition-[height]"
                     data-tree-view-target="content"
                     hidden>
                  <div class="flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm text-neutral-600 dark:text-neutral-300 hover:bg-neutral-100 dark:hover:bg-neutral-700 transition-colors duration-150 outline-none focus:underline">
                    <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M15.16,6.25h-3.41c-.552,0-1-.448-1-1V1.852"></path><path d="M2.75,14.25V3.75c0-1.105,.895-2,2-2h5.586c.265,0,.52,.105,.707,.293l3.914,3.914c.188,.188,.293,.442,.293,.707v7.586c0,1.105-.895,2-2,2H4.75c-1.105,0-2-.895-2-2Z"></path></g></svg>
                    <span>button.tsx</span>
                  </div>
                </div>
              </div>
              <!-- Files in "components" -->
              <div class="flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm text-neutral-600 dark:text-neutral-300 hover:bg-neutral-100 dark:hover:bg-neutral-700 transition-colors duration-150 outline-none focus:underline">
               <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M15.16,6.25h-3.41c-.552,0-1-.448-1-1V1.852"></path><path d="M2.75,14.25V3.75c0-1.105,.895-2,2-2h5.586c.265,0,.52,.105,.707,.293l3.914,3.914c.188,.188,.293,.442,.293,.707v7.586c0,1.105-.895,2-2,2H4.75c-1.105,0-2-.895-2-2Z"></path></g></svg>
                <span>header.tsx</span>
              </div>
              <div class="flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm text-neutral-600 dark:text-neutral-300 hover:bg-neutral-100 dark:hover:bg-neutral-700 transition-colors duration-150 outline-none focus:underline">
                <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M15.16,6.25h-3.41c-.552,0-1-.448-1-1V1.852"></path><path d="M2.75,14.25V3.75c0-1.105,.895-2,2-2h5.586c.265,0,.52,.105,.707,.293l3.914,3.914c.188,.188,.293,.442,.293,.707v7.586c0,1.105-.895,2-2,2H4.75c-1.105,0-2-.895-2-2Z"></path></g></svg>
                <span>footer.tsx</span>
              </div>
            </div>
          </div>
        </div>
      </div>
      <!-- Folder "lib" -->
      <div class="overflow-hidden">
        <button type="button"
                data-action="click->tree-view#toggle"
                aria-controls="tree-content-lib"
                aria-expanded="true"
                data-state="open"
                class="flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm hover:bg-neutral-100 dark:hover:bg-neutral-700 transition-colors duration-150 outline-none focus:underline">
          <svg data-tree-view-target="icon" class="folder-open" xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M5,14.75h-.75c-1.105,0-2-.895-2-2V4.75c0-1.105,.895-2,2-2h1.825c.587,0,1.144,.258,1.524,.705l1.524,1.795h4.626c1.105,0,2,.895,2,2v1"></path><path d="M16.148,13.27l.843-3.13c.257-.953-.461-1.89-1.448-1.89H6.15c-.678,0-1.272,.455-1.448,1.11l-.942,3.5c-.257,.953,.461,1.89,1.448,1.89H14.217c.904,0,1.696-.607,1.931-1.48Z"></path></g></svg>
          <span class="font-medium">lib</span>
        </button>
        <div id="tree-content-lib"
             data-state="open"
             role="region"
             class="ml-4 pl-2 border-l border-neutral-200 dark:border-neutral-700 space-y-1 overflow-hidden transition-[height]"
             data-tree-view-target="content">
          <div class="flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm text-neutral-600 dark:text-neutral-300 hover:bg-neutral-100 dark:hover:bg-neutral-700 transition-colors duration-150 outline-none focus:underline">
            <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><g fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" stroke="currentColor"><path d="M15.16,6.25h-3.41c-.552,0-1-.448-1-1V1.852"></path><path d="M2.75,14.25V3.75c0-1.105,.895-2,2-2h5.586c.265,0,.52,.105,.707,.293l3.914,3.914c.188,.188,.293,.442,.293,.707v7.586c0,1.105-.895,2-2,2H4.75c-1.105,0-2-.895-2-2Z"></path></g></svg>
            <span>utils.ts</span>
          </div>
        </div>
      </div>
    </div>
  </div>
</div>

Configuration

The tree view component is powered by a Stimulus controller that provides keyboard navigation, smooth animations, and flexible folder/file management.

Controller Setup

Basic tree view structure with required data attributes:

<div data-controller="tree-view" data-tree-view-animate-value="true">
  <div class="overflow-hidden">
    <button type="button"
            data-action="click->tree-view#toggle"
            aria-controls="tree-content-folder"
            aria-expanded="false"
            data-state="closed">
      <svg data-tree-view-target="icon"><!-- Folder icon --></svg>
      <span>Folder Name</span>
    </button>
    <div id="tree-content-folder"
         data-state="closed"
         role="region"
         data-tree-view-target="content"
         hidden>
      <!-- Nested content -->
    </div>
  </div>
</div>

Configuration Values

Prop	Description	Type	Default
animate	Controls whether folder expand/collapse animations are enabled	`Boolean`	`true`

Targets

Target	Description	Required
icon	The folder icon that changes between open and closed states	Optional
content	The collapsible content area containing nested items	Required

Actions

Action	Description	Usage
toggle	Toggles the open/closed state of a folder in the tree	`data-action="click->tree-view#toggle"`

Required Attributes

Attribute	Description	Example
aria-controls	Links the button to its content area	`aria-controls="tree-content-folder"`
aria-expanded	Indicates whether the folder is open (true) or closed (false)	`aria-expanded="false"`
data-state	Visual state indicator for styling	`data-state="closed"`
role	Accessibility role for content areas	`role="region"`
hidden	Hides closed content from screen readers and layout	`hidden`

Accessibility Features

Keyboard Navigation: Use ↑ ↓ arrows to navigate between folders
ARIA Support: Proper aria-expanded and aria-controls attributes
Screen Reader Friendly: Semantic regions and proper focus management
Keyboard Actions: Enter and Space to toggle folders

Icon Management

The controller automatically handles folder icon transitions:

Closed Folders: Display a closed folder icon
Open Folders: Display an open folder icon with papers/documents
Automatic Switching: Icons change automatically based on folder state

Animation Control

The tree view supports smooth height animations:

Smooth Expand: Content animates from height 0 to natural height
Smooth Collapse: Content animates from natural height to 0
Disable Animations: Set data-tree-view-animate-value="false" for instant toggling

Styling Classes

Key CSS classes used in the component:

overflow-hidden: Required for smooth height animations
transition-[height]: Enables height transition animations
border-l: Creates visual hierarchy lines
ml-4 pl-2: Creates proper indentation for nested items

Usage Notes

Each folder button must have a unique aria-controls value
Content areas must have matching id attributes
Use data-state="open" to have folders start expanded
File items don't need the toggle action, only folder items do
The controller handles keyboard navigation automatically for all clickable elements

Two Factor