FileTree

A file-system-flavored specialization of TreeView. It maps a file/folder model onto the tree, auto-assigns file-type icons by extension (plus open/closed folder glyphs), and adds drag-and-drop import of OS files onto a folder or the root. Expansion, selection, keyboard navigation, and sizing are inherited from TreeView unchanged.

Live Preview

Import

import { FileTree } from 'entangle-ui';
import type { FileTreeNode } from 'entangle-ui';

Usage

FileTree takes a nested array of FileTreeNodes. Each node has a kind of 'file' or 'folder'; folders carry children. File-type icons are derived from the file name (or an explicit ext), so you don’t assign them yourself.

const nodes: FileTreeNode[] = [
  {
    id: 'src',
    name: 'src',
    kind: 'folder',
    children: [
      { id: 'btn', name: 'Button.tsx', kind: 'file' },
      { id: 'logo', name: 'logo.svg', kind: 'file' },
    ],
  },
  { id: 'readme', name: 'README.md', kind: 'file' },
];

<FileTree nodes={nodes} defaultExpandedIds={['src']} />;

Expanding folders

Clicking anywhere on a folder row toggles it open/closed — not just the chevron (expandOnClick, on by default). Files are unaffected. Set expandOnClick={false} to require a chevron click instead.

// Whole-row toggle (default)
<FileTree nodes={nodes} />

// Require the chevron
<FileTree nodes={nodes} expandOnClick={false} />

Drag-and-drop import

Provide onImport to enable the import drop zone. Dropping OS files onto a folder targets that folder; dropping a file row targets its parent folder; dropping on empty space targets the root (targetFolder: null). The active target folder is highlighted while dragging. FileTree only reports intent — apply the change to your data and pass back fresh nodes.

Drag-and-drop import

<FileTree
  nodes={nodes}
  onImport={({ files, targetFolder }) => {
    uploadInto(targetFolder?.id ?? 'root', files);
  }}
/>

File-type icons

Icons are resolved from the file extension into a small set of buckets (image, media, code, archive, text) backed by the library icon set, with open/closed folder glyphs. Pass resolveIcon to override per node — return undefined to fall back to the built-in icon.

File-type icons

<FileTree
  nodes={nodes}
  resolveIcon={(node, { expanded }) =>
    node.name.endsWith('.json') ? <StarIcon color="warning" /> : undefined
  }
/>

The classifyExtension / getFileIconKind helpers used internally are also exported, in case you want to drive your own UI from the same mapping.

Coloring icons

Built-in icons follow the theme (folders use text.secondary, files text.muted), so a theme change re-colors them. For per-type or per-node colors, return a colored icon from resolveIcon — every library icon takes a color prop (a theme key like accent / success / warning, or any CSS color).

Colored icons by type

<FileTree
  nodes={nodes}
  resolveIcon={(node, { expanded }) => {
    if (node.kind === 'folder') {
      return expanded ? (
        <FolderOpenIcon color="accent" />
      ) : (
        <FolderIcon color="accent" />
      );
    }
    if (node.name.endsWith('.png')) return <ImageIcon color="success" />;
    return undefined; // fall back to the built-in icon
  }}
/>

Selection

Selection reuses TreeView’s controlled/uncontrolled model verbatim — single (default), multiple (Ctrl / Shift click, Ctrl+A), or none.

Selection

<FileTree
  nodes={nodes}
  selectionMode="multiple"
  selectedIds={selected}
  onSelectionChange={setSelected}
/>

Sizes

Sizes

<FileTree nodes={nodes} size="sm" />
<FileTree nodes={nodes} size="md" />
<FileTree nodes={nodes} size="lg" />

Relationship to TreeView

FileTree renders a TreeView internally and feeds it derived nodes — it does not reimplement expansion, selection, or keyboard navigation. The same controlled/uncontrolled props (expandedIds / defaultExpandedIds, selectedIds / defaultSelectedIds) and the same keyboard behaviour apply. Reach for TreeView directly when you need a generic hierarchy; reach for FileTree when the data is files and folders.

The drag-and-drop import is built on top of TreeView’s generic drop-target props (dropTargetId, onNodeDragOver / onNodeDragLeave / onNodeDrop), which are available for building your own drop interactions on a plain TreeView as well.

Styling

FileTree is themed entirely through the --etui-* theme contract — no colors, spacings, or fonts are hard-coded. There are three ways to restyle it.

Render & content overrides

• className / style are applied to the root container (style is also the place to set --etui-* overrides — they cascade to every row).
• resolveIcon swaps a node’s icon; renderNode replaces a row’s whole inner content (icon + label); renderActions adds trailing controls.

Targeting hooks

The internal class names are compiled (hashed) by Vanilla Extract, so target the stable structural hooks instead:

Selector	Matches
[role="tree"]	The tree region.
[role="treeitem"]	Every row.
[role="treeitem"][aria-selected="true"]	Selected rows.
[role="treeitem"][data-drop-target="true"]	The folder currently highlighted as a drop target.
[data-root-active="true"]	The container while files are dragged over the root.
#treenode-<id>	A specific row by node id.

Theme tokens consumed

Override these on any ancestor to re-skin FileTree (or use createCustomTheme(...) for a whole-app palette):

Token	Used for
--etui-color-accent-primary	Selected-row tint and the active drop-target highlight (row + root).
--etui-color-surface-hover	Row hover background.
--etui-color-border-focus	Focused-row ring.
--etui-color-border-default	Guide lines.
--etui-color-text-primary	File / folder names; chevron hover.
--etui-color-text-secondary	Folder icons.
--etui-color-text-muted	File icons, chevrons, and empty-state text.
--etui-radius-sm	Container corner rounding.
--etui-spacing-xs, --etui-spacing-md	Icon gap / row padding; empty-state padding.
--etui-font-size-md, --etui-font-size-lg	Size-scaled label text.
--etui-line-height-normal	Label line height.
--etui-transition-fast	Chevron rotation and hover transitions.

Re-skinned via token overrides

<FileTree
  nodes={nodes}
  style={{
    ['--etui-color-accent-primary' as string]: '#d946ef',
    ['--etui-color-text-secondary' as string]: '#d946ef',
  }}
/>

Internationalization

FileTree renders no copy of its own — file and folder names come from your data, and the file-type icons are decorative. The only built-in strings are the tree’s accessible name and the empty-state text, both overridable through the labels prop (a Partial<FileTreeLabels>, so anything you omit keeps its English default). An explicit aria-label / emptyContent still wins over the matching label.

Localized labels (Polish)

<FileTree
  nodes={nodes}
  labels={{ treeLabel: 'Drzewo plików', emptyLabel: 'Brak plików' }}
/>

The English defaults are exported as DEFAULT_FILE_TREE_LABELS (spread and tweak it when you only need to change one key).

Key	Type	Default
treeLabel	string	"File tree"
emptyLabel	string	"No files"

Props

Prop	Type	Default	Description
nodes	FileTreeNode[]	—	Tree data — array of root-level files/folders.
expandedIds	string[]	—	Expanded node IDs (controlled).
defaultExpandedIds	string[]	—	Default expanded node IDs (uncontrolled).
onExpandedChange	(expandedIds: string[]) => void	—	Fired when expanded nodes change.
selectedIds	string[]	—	Selected node IDs (controlled).
defaultSelectedIds	string[]	—	Default selected node IDs (uncontrolled).
selectionMode	'single' | 'multiple' | 'none'	'single'	Selection mode (reused from TreeView).
onSelectionChange	(selectedIds: string[]) => void	—	Fired when selected nodes change.
size	'sm' | 'md' | 'lg'	'md'	Row size.
indent	number	16	Indentation per depth level in pixels.
showChevrons	boolean	true	Whether to show expand/collapse chevrons for folders.
showGuideLines	boolean	false	Whether to show connecting guide lines.
expandOnClick	boolean	true	Toggle a folder open/closed when its whole row is clicked (not just the chevron).
maxHeight	number | string	—	Maximum height before the tree scrolls.
resolveIcon	(node: FileTreeNode, state: { expanded: boolean }) => ReactNode	—	Override a node icon. Return undefined to fall back to the built-in extension map.
renderNode	(node: FileTreeNode, state: FileTreeNodeState) => ReactNode	—	Fully replace a node's inner content (icon + label).
renderActions	(node: FileTreeNode, state: FileTreeNodeState) => ReactNode	—	Render trailing actions on the right of a row.
emptyContent	ReactNode	—	Content shown when nodes is empty.
onImport	(payload: { files: File[]; targetFolder: FileTreeNode | null }) => void	—	Fired when OS files are dropped onto a folder or the root. Presence enables the import drop zone.
onNodeClick	(node: FileTreeNode, event: MouseEvent) => void	—	Fired when a node is clicked.
onNodeDoubleClick	(node: FileTreeNode, event: MouseEvent) => void	—	Fired when a node is double-clicked.
onNodeContextMenu	(node: FileTreeNode, event: MouseEvent) => void	—	Fired when a node is right-clicked.
labels	Partial<FileTreeLabels>	—	Override built-in strings (tree accessible name, empty-state text). Merged onto the defaults.
aria-label	string	—	Accessible name for the tree. Wins over labels.treeLabel; lands on the role="tree" element.
className	string	—	Additional CSS class names (on the root container).
testId	string	—	Test identifier for automated testing.

FileTreeNode

Property	Type	Description
id	string	Stable unique id within the tree.
name	string	Display name, e.g. "Button.tsx".
kind	'file' | 'folder'	File vs. folder. Folders accept dropped files.
ext	string	Extension override (no dot). Inferred from name.
path	string	Optional path (informational; surfaced unchanged).
children	FileTreeNode[]	Child entries (folders).
disabled	boolean	Dim + non-interactive.
data	Record<string, unknown>	Arbitrary consumer payload.

Accessibility

Accessibility is inherited from TreeView:

• The container is role="tree"; each row is role="treeitem" with aria-expanded / aria-selected and aria-level.
• aria-activedescendant tracks the focused node; focus is scrolled into view.
• Full keyboard navigation (Arrow keys, Home/End, Enter, Space, Ctrl+A, Shift+Arrow range selection). File-type icons are decorative (aria-hidden), so the file name is the accessible label.