File Tree

Usage

Anatomy

Import the FileTree component and access all parts using dot notation.

import {FileTree} from "@heroui-pro/react";

<FileTree>
  <FileTree.Section>
    <FileTree.Header />
    <FileTree.Item>
      <FileTree.Indicator />
    </FileTree.Item>
  </FileTree.Section>
</FileTree>

Reduced Motion

Pass reduceMotion to disable expand/collapse animation while keeping the same tree behavior.

With Icons

Custom Indicator

Drag And Drop

Dynamic Collection

Sizes

Guide Lines

Multiple Selection

PR File Review

CSS Classes

Base & Size Classes

• .file-tree — Root tree container. Sets flex column layout, padding, and outline.
• .file-tree--sm — Small size. Tighter indent and smaller item padding/font.
• .file-tree--md — Medium size (default). Moderate indent and padding.
• .file-tree--lg — Large size. Wider indent and larger item padding/font.

Element Classes

• .file-tree__item — Individual tree row (file or folder). Rounded with interactive cursor.
• .file-tree__item--sm — Small item sizing (text-xs, compact padding).
• .file-tree__item--md — Medium item sizing (text-sm, default padding).
• .file-tree__item--lg — Large item sizing (text-base, spacious padding).
• .file-tree__item-content — Flex layout wrapper inside each item. Handles indent via --tree-item-level.
• .file-tree__guide-line — Vertical indent guide spanning the full row height, one per parent level.
• .file-tree__guide-line--hover — Guide lines only visible when the tree is hovered.
• .file-tree__guide-line--none — Guide lines hidden (display: none).
• .file-tree__chevron — Expand/collapse toggle button. Hidden when item has no children.
• .file-tree__indicator — The expand/collapse icon inside the chevron. Rotates 90° when expanded.
• .file-tree__icon — File/folder icon area next to the label.
• .file-tree__label — Text label for the tree item. Truncates with ellipsis.
• .file-tree__section — Optional grouping wrapper for related items.
• .file-tree__section-header — Section heading label. Muted, uppercase-style text.
• .file-tree__drag-handle — Grip button rendered when dragging is allowed. Appears on hover.

Interactive States

• Hover: &:hover / [data-hovered="true"] on .file-tree__item — applies bg-default.
• Pressed: &:active / [data-pressed="true"] on .file-tree__item — applies bg-default-hover.
• Focus visible: [data-focus-visible="true"] on .file-tree__item — applies focus ring.
• Disabled: [aria-disabled="true"] on .file-tree__item — applies disabled opacity.
• Selected: [data-selected="true"] on .file-tree__item — applies bg-default with merged border-radius for adjacent selected items.
• Expanded: [data-expanded] on .file-tree__item — rotates .file-tree__indicator to 90°.
• Dragging: [data-dragging] on .file-tree__item — reduced opacity (0.4).
• Drop target: [data-drop-target] on .file-tree__item — accent background with outline.
• Empty tree: [data-empty] on .file-tree — centered italic placeholder text.

CSS Variables

• --file-tree-indent — Indentation width per nesting level (varies by size).
• --file-tree-item-px — Horizontal padding for item content.
• --file-tree-guide-color — Color of the indent guide lines (default: color-mix(in srgb, currentColor 10%, transparent)).

API Reference

FileTree

The root tree container. Renders a <div role="treegrid"> internally.

Also supports all RAC Tree props.

FileTree.Item

An individual tree row representing a file or folder.

Also supports all RAC TreeItem props.

FileTree.Indicator

Custom expand/collapse icon used inside the chevron button. Defaults to a ChevronRight icon that rotates on expand.

FileTree.Section

Groups related tree items under an optional header.

Also supports all RAC TreeSection props.

FileTree.Header

Section heading label rendered above a group of items.

Also supports all RAC TreeHeader props.

useFileTree

A utility hook for working with tree data structures.

const { expandableKeys, filterTree, leaves } = useFileTree({ items });

Returns:

useFileTreeDrag

A hook that wires up drag-and-drop for the file tree using RAC's useDragAndDrop.

const { dragAndDropHooks } = useFileTreeDrag({ tree });

Returns: { dragAndDropHooks } — pass directly to the <FileTree> component.