@live-codes/file-tree

A zero-dependency, framework-agnostic file tree component written in TypeScript. Features multiple selection, drag-and-drop, context menus, keyboard navigation, theming, i18n, and RTL support.

For use in LiveCodes.

Install

npm install @live-codes/file-tree

Quick Start

import { FileTree } from "@live-codes/file-tree";

const tree = new FileTree("#container", {
  data: [
    { path: "src/index.ts", type: "file" },
    { path: "src/utils/helpers.ts", type: "file" },
    { path: "src/utils/constants.ts", type: "file" },
    { path: "package.json", type: "file" },
    { path: "README.md", type: "file" },
  ],
  selected: "src/index.ts",
  theme: "dark",
  direction: "ltr",
});

// Listen to events
tree.on("select", (e) => console.log("Selected:", e.path));
tree.on("rename", (e) => console.log("Renamed:", e.oldPath, "->", e.path));
tree.on("copy", (e) => console.log("Copied:", e.oldPath, "->", e.path));
tree.on("move", (e) => console.log("Moved:", e.oldPath, "->", e.path));
tree.on("delete", (e) => {
  e.preventDefault();
  const confirmed = confirm(`Delete "${e.path}"?`);
  if (confirmed) tree.removeNode(e.path);
});
tree.on("change", (e) => console.log("Tree changed:", e.tree));

Parent folders are automatically created from paths. In the example above, the src and src/utils folders are inferred from the file paths — you don't need to declare them.

Styles are injected automatically. The component's CSS is bundled and added to document.head (as a <style id="ft-styles"> tag) the first time you create a FileTree — no separate stylesheet import needed. If you prefer to manage the stylesheet yourself, pass injectStyles: false to the constructor and import @live-codes/file-tree/styles.css directly:

import { FileTree } from "@live-codes/file-tree";
import "@live-codes/file-tree/styles.css";

const tree = new FileTree("#container", {
  injectStyles: false, // manage styles manually
  data: [...],
});

You can also declare folders explicitly when you want empty folders or want to attach metadata:

const tree = new FileTree("#container", {
  data: [
    { path: "src", type: "folder" },
    { path: "src/index.ts", type: "file" },
    { path: "dist", type: "folder" }, // empty folder
  ],
});

Constructor

new FileTree(container: HTMLElement | string, options?: FileTreeOptions)

The container argument can be a CSS selector string or an HTMLElement.

Node Data

interface FileTreeNodeData {
  /** Full path (e.g. "src/utils/helpers.ts") — used as the unique identifier. */
  path: string;
  /** Whether this is a file or folder. */
  type: "file" | "folder";
  /** Custom SVG string to override the default icon. */
  icon?: string;
  /** Arbitrary user data. */
  meta?: Record<string, unknown>;
}

createNode Helper

The createNode utility returns an array that includes the requested node plus all intermediate parent folders:

import { createNode } from "@live-codes/file-tree";

const nodes = createNode("src/components/Button.tsx", "file");
// Returns:
// [
//   { path: 'src', type: 'folder' },
//   { path: 'src/components', type: 'folder' },
//   { path: 'src/components/Button.tsx', type: 'file' },
// ]

Spread multiple createNode calls into your data array — duplicates are automatically deduplicated:

const tree = new FileTree("#container", {
  data: [
    ...createNode("src/index.ts", "file"),
    ...createNode("src/utils.ts", "file"),
    ...createNode("package.json", "file"),
  ],
});

Creating Nested Paths on the Fly

When creating a file or folder through the UI (toolbar buttons, context menu) or renaming one (double-click, F2, or the renameNode API), you can type a name containing slashes and the intermediate folders are created automatically:

tree.renameNode("logo.svg", "images/logo.svg"); // file
// Creates: { path: "images", type: "folder" }, { path: "images/logo.svg", type: "file" }

tree.renameNode("src", "components/ui"); // folder
// Renames: src → components/ui (and moves any children along)

A few rules apply:

• Slashes are only allowed in names entered through create/rename flows. Existing nodes with nested paths (from data or addNode) keep working as before.
• Renaming a file to dir/file.txt creates the dir folder and moves the file into it.
• Renaming a folder to a/b moves the folder (and its contents) to b under new folder a. A folder cannot be renamed inside itself (e.g. a → a/b).
• Backslashes (\) are rejected — they are treated as path separators on Windows.

Options

| Option | Type | Default | Description | | -------------- | ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | data | FileTreeNodeData[] | [] | Initial flat data array | | selected | string | '' | Path of the initially selected node | | theme | 'light' \| 'dark' | 'dark' | Color theme | | direction | 'ltr' \| 'rtl' | 'ltr' | Text direction | | indent | number | 16 | Pixels per indentation level | | dragAndDrop | boolean | true | Enable drag and drop | | readOnly | boolean | false | Disable all UI edits: keyboard shortcuts, context menu and drag & drop. Toolbar create buttons are hidden and double-click rename is disabled. Programmatic methods (addNode, renameNode, ...) still work | | injectStyles | boolean | true | Inject the bundled CSS into document.head automatically. Set to false to manage styles manually (e.g. import @live-codes/file-tree/styles.css) | | toolbar | ToolbarOptions \| false | See below | Toolbar configuration | | contextMenu | ContextMenuOptions \| false | See below | Context menu configuration | | icons | Record<string, string> | {} | Custom file extension → SVG icon map | | sort | boolean \| Comparator | true | Sort nodes (folders first, alphabetical) |

ToolbarOptions

{
  createFile?: boolean;    // default: true
  createFolder?: boolean;  // default: true
  expandAll?: boolean;     // default: true
  collapseAll?: boolean;   // default: true
  custom?: ToolbarButton[];
}

Custom Toolbar Button

interface ToolbarButton {
  id: string;
  label: string; // Button tooltip (shown on hover)
  icon?: string; // SVG string
  onClick: () => void;
  order?: number; // Position among the built-in buttons
}

Built-in buttons own fixed slots: createFile=0, createFolder=1, expandAll=2, collapseAll=3. order: N on a custom button inserts it after the built-in that owns slot N — so order: 1 makes it the third button (after New File and New Folder). Custom buttons without order are appended after all built-ins in array order. Disabled built-ins simply leave their slot empty.

new FileTree(container, {
  toolbar: {
    custom: [
      {
        id: "refresh",
        label: "Refresh",
        icon: icons.refreshIcon,
        onClick: () => {},
        order: 1,
      },
      {
        id: "info",
        label: "Info",
        icon: icons.file,
        onClick: () => {},
        order: 3,
      },
    ],
  },
});

Two custom buttons with the same order sit next to each other and keep their array order — swap the array entries to reverse them:

custom: [
  { id: "info", label: "Info", onClick: () => {}, order: 1 },
  { id: "refresh", label: "Refresh", onClick: () => {}, order: 1 },
],
// New File, New Folder, Info, Refresh, Expand All, Collapse All

order is just a sort key, so fractional values give you fine-grained control between any two buttons. To make a custom button the very first one, use a negative order (any built-in owns slot 0, so a value below 0 sorts before it):

custom: [
  { id: "favorite", label: "Favorite", icon: icons.folder, onClick: () => {}, order: -1 },
],
// Favorite, New File, New Folder, Expand All, Collapse All

ContextMenuOptions

{
  createFile?: boolean;    // default: true
  createFolder?: boolean;  // default: true
  rename?: boolean;        // default: true
  delete?: boolean;        // default: true
  copy?: boolean;          // default: true  (copy node to clipboard)
  cut?: boolean;           // default: true  (cut node to clipboard)
  paste?: boolean;         // default: true  (paste clipboard into tree)
  copyPath?: boolean;      // default: true  (copy node path to system clipboard)
  custom?: ContextMenuItem[];
}

Custom Toolbar Button

interface ToolbarButton {
  id: string;
  label: string;
  icon?: string; // SVG string
  title?: string; // Tooltip
  onClick: () => void;
}

Custom Context Menu Item

interface ContextMenuItem {
  id: string;
  label: string;
  icon?: string;
  shortcut?: string;
  visible?: (node: FileTreeNodeData) => boolean;
  // `nodes` = all selected nodes (or just the right-clicked node when it is
  // not part of a multi-selection); `primaryNode` = the right-clicked node.
  onClick: (nodes: FileTreeNodeData[], primaryNode: FileTreeNodeData) => void;
}

i18n

The built-in UI strings (toolbar tooltips and context menu labels) are in English by default. To localize them, pass a translation function via the t option. It receives a FileTreeStringKey and returns the string to display:

import { FileTree, type FileTreeStringKey } from "@live-codes/file-tree";

const strings: Record<FileTreeStringKey, string> = {
  newFile: "Nouveau fichier",
  newFolder: "Nouveau dossier",
  expandAll: "Tout déplier",
  collapseAll: "Tout replier",
  copy: "Copier",
  cut: "Couper",
  paste: "Coller",
  copyPath: "Copier le chemin",
  rename: "Renommer",
  delete: "Supprimer",
};

const tree = new FileTree("#container", {
  data: [...],
  t: (key) => strings[key],
});

The library never tracks or manages languages — it only calls your function. If t returns undefined for a key, the built-in English string is used as a fallback. The English defaults are exported as defaultStrings and can be used to build a full locale object:

import { defaultStrings, type FileTreeStringKey } from "@live-codes/file-tree";

const strings: Record<FileTreeStringKey, string> = {
  ...defaultStrings,
  newFile: "Nuevo archivo",
  // only override what you need
};

Custom toolbar buttons and context menu items are entirely user-supplied, so their labels are never passed through t — translate them yourself.

Methods

Tree Navigation

| Method | Description | | -------------------------- | ------------------------------------------------------------ | | expand(path) | Expand a folder | | collapse(path) | Collapse a folder | | expandAll() | Expand all folders | | collapseAll() | Collapse all folders | | select(path \| string[]) | Select a node (or multiple nodes); parents are auto-expanded | | selectAll() | Select every node in the tree | | clearSelection() | Clear the current selection | | getSelectedNode() | Get the primary (first) selected node, or null | | getSelectedNodes() | Get all currently selected nodes as an array |

Data Operations

| Method | Description | | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | addNode(node) | Add a node (parent folders auto-created from path) | | deleteNode(path \| string[]) | Delete node(s) and their descendants; emits a cancellable delete event first (call preventDefault() to intercept, e.g. for a confirmation dialog) | | removeNode(path \| string[]) | Remove node(s) and their descendants (not cancellable) | | renameNode(path, newName) | Rename a node (changes only the last path segment; slashes in newName create intermediate folders on the fly) | | moveNode(sourcePath \| string[], targetParentPath) | Move node(s) to a new parent folder ('' or null for root) | | moveTo(oldPath, newPath) | Move a node to an exact destination path, renaming it in the same step (combines moveNode + renameNode); missing intermediate folders are auto-created; returns false if invalid (conflict, or a folder moved inside itself) | | copyNode(sourcePath \| string[], targetParentPath) | Copy node(s) to a new parent folder ('' or null for root); copying to the same location duplicates them with a copy suffix before the extension (e.g. index copy.ts); returns the new path(s) | | setData(data) | Replace the entire tree | | getData() | Get a clone of the flat data array | | getNode(path) | Get a single node by path | | getSelectedNode() | Get the currently selected node |

Theme & Direction

| Method | Description | | ------------------------------ | --------------------- | | setTheme('light' \| 'dark') | Change the theme | | getTheme() | Get current theme | | setDirection('ltr' \| 'rtl') | Change text direction | | getDirection() | Get current direction |

Lifecycle

| Method | Description | | ----------- | ------------------------------------------ | | destroy() | Remove the tree and clean up all listeners |

Events

tree.on(eventType, handler);
tree.off(eventType, handler);

| Event | Fired when | | ---------- | ----------------------------------------------- | | select | The selection changes | | expand | A folder is expanded | | collapse | A folder is collapsed | | create | A new node is created (after name is committed) | | copy | A node is copied | | move | A node is moved | | rename | A node is renamed | | delete | One or more nodes are deleted | | drop | External files are dropped into the tree | | change | Any structural change to the tree data |

Every event handler receives a FileTreeEvent:

interface FileTreeEvent {
  type: FileTreeEventType;
  source: "ui" | "api"; // What triggered the event
  node: FileTreeNodeData; // The affected node (first node for multi-node ops)
  path: string; // Current path (same as node.path)
  oldPath?: string; // Previous path (rename/move)
  paths?: string[]; // All affected paths (multi-select delete/select, etc.)
  nodes?: FileTreeNodeData[]; // Node data for each path in `paths`
  parentPath: string; // Parent folder path ('' for root)
  parentNode: FileTreeNodeData | null;
  tree: FileTreeNodeData[]; // Full flat data snapshot
  data?: { files: FileList; items: DataTransferItemList }; // Drag-and-drop
}

For multi-node operations (e.g. deleting a multi-selection), a single event is emitted with paths/nodes containing every affected node; path/node always refer to the first entry. Calling preventDefault() on a delete event cancels the whole batch.

source tells you whether the event was triggered by user interaction ("ui" — clicks, keyboard, context menu, drag & drop) or by a programmatic API call ("api" — addNode, renameNode, moveNode, copyNode, removeNode, select, ...). This lets you react differently to the same event depending on its origin:

tree.on("delete", (e) => {
  if (e.source === "ui") {
    // User pressed Delete / context menu — show a confirmation
    // dialog and call tree.removeNode() if confirmed.
    e.preventDefault();
  } else {
    // Already deleted programmatically — nothing to do.
  }
});

Keyboard Shortcuts

| Key | Action | | -------------------- | ------------------------------------- | | ↑ / ↓ | Navigate between visible nodes | | Shift + ↑ / ↓ | Extend selection by a range | | Ctrl/Cmd + ↑ / ↓ | Move focus without changing selection | | → | Expand folder or move to first child | | ← | Collapse folder or move to parent | | Enter / Space | Toggle folder expand/collapse | | F2 | Rename selected node | | Delete | Delete selected node(s) | | Ctrl/Cmd + A | Select all nodes | | Ctrl/Cmd + C | Copy selected node(s) | | Ctrl/Cmd + X | Cut selected node(s) | | Ctrl/Cmd + V | Paste clipboard into selected folder | | Ctrl/Cmd + Click | Toggle a node in the selection | | Shift + Click | Select a range from the anchor |

Operations (copy, cut, delete, move, drag) apply to all selected nodes. Dragging a selected node drags the whole selection. Right-clicking a node that is part of a multi-selection keeps the selection, so context-menu actions apply to all of it; right-clicking an unselected node replaces the selection.

Read-Only Mode

Pass readOnly: true to disable every way of editing the tree from the UI — keyboard shortcuts (rename, delete, copy/cut/paste), the context menu, double-click rename, toolbar create buttons and drag & drop:

const tree = new FileTree("#container", {
  data: [...],
  readOnly: true, // view-only tree
});

Navigation (arrow keys, selection, expand/collapse) still works, and the programmatic API (addNode, renameNode, moveNode, copyNode, removeNode, ...) remains fully available.

CSS Customization

All visual properties are controlled by CSS custom properties. Override them on .ft-root or on theme-specific selectors:

.ft-root[data-theme="dark"] {
  --ft-bg: #1a1b26;
  --ft-color: #c0caf5;
  --ft-node-hover: #292e42;
  --ft-node-selected: #33467c;
  --ft-drop-indicator: #7aa2f7;
  /* ... see styles.css for all variables */
}

Integration with Custom Apps

Map the file tree variables to your app's existing CSS variables:

.ft-root[data-theme="dark"] {
  --ft-bg: var(--layout);
  --ft-color: var(--link);
  --ft-node-hover: var(--darker-bg-active);
  --ft-node-selected: var(--dark-bg-active);
  --ft-toolbar-bg: var(--layout);
  --ft-toolbar-border: var(--color30);
  --ft-context-bg: var(--dropdown-bg-color);
  --ft-context-border: var(--dark-bg-color);
  --ft-context-color: var(--dropdown-color);
  --ft-context-hover: var(--dropdown-bg-active);
  --ft-input-bg: var(--input-bg-color);
  --ft-input-color: var(--input-color);
  --ft-input-border: var(--input-border-color);
  --ft-border-radius: var(--rs);
}

.ft-root[data-theme="light"] {
  --ft-bg: var(--layout);
  --ft-color: var(--dark-color);
  --ft-node-hover: var(--dark-bg-active);
  --ft-node-selected: var(--color80);
  --ft-toolbar-bg: var(--layout);
  --ft-toolbar-border: var(--color80);
  --ft-context-bg: var(--dropdown);
  --ft-context-color: var(--dark-color);
}

Utility Exports

The library exports a few utility functions for working with paths:

import {
  createNode, // Create node(s) with auto parent folders
  normalizePath, // Normalize a path string
  getName, // "src/index.ts" → "index.ts"
  getParentPath, // "src/index.ts" → "src"
  getExtension, // "index.ts" → "ts"
} from "@live-codes/file-tree";

Icons

The icon set used internally by the tree is available under the icons namespace, so you can reuse the same SVG strings (for custom toolbar buttons, context-menu items, or anywhere else):

import { icons } from "@live-codes/file-tree";

icons.folder; // '<svg ...>...</svg>'
icons.fileTs; // TypeScript file badge
icons.newFile; // toolbar "new file" icon

All icons are string values — full <svg> markup that renders with currentColor where applicable.

Available exports:

| Name | Description | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | chevron | Expand/collapse chevron | | folder / folderOpen | Folder (closed / open) | | file | Generic file icon | | fileTs, fileJs, ... | Per-extension file badges (ts, js, tsx, jsx, html, css, scss, json, md, yaml, svg, png, jpg, gif, webp, py, rb, rs, go, java, php, sh, sql, xml, toml, lock, env, vue, txt) | | newFile, newFolder | Toolbar create buttons | | expandAllIcon, collapseAllIcon | Toolbar expand/collapse all | | editIcon, trashIcon | Toolbar edit/delete | | copyIcon, cutIcon, pasteIcon | Clipboard action icons | | refreshIcon | Refresh / reload icon (circular arrow) | | defaultIconMap | Extension → icon registry (used internally) | | defaultNameIconMap | Filename → icon registry (e.g. README.md) |

Browser Support

All modern browsers (Chrome, Firefox, Safari, Edge). Uses standard HTML5 Drag and Drop API and CSS custom properties.

Development

npm install          # install dependencies
npm run dev          # watch mode build
npm test             # run the test suite (Vitest + jsdom)
npm run test:watch   # run tests in watch mode
npm run test:coverage # run tests with coverage report + thresholds
npm run typecheck    # type-check src and tests
npm run lint         # lint src and tests
npm run build        # production build

License

MIT