@live-codes/file-tree

@live-codes/file-tree

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

For use in LiveCodes.

Install

npm install @live-codes/file-tree

Quick Start

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

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("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.

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"),
  ],
});

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
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[];
}

ContextMenuOptions

{
  createFile?: boolean;    // default: true
  createFolder?: boolean;  // default: true
  rename?: boolean;        // default: true
  delete?: boolean;        // default: true
  copy?: boolean;          // default: false
  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;
  onClick: (node: FileTreeNodeData) => void;
}

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)	Select a node

Data Operations

Method	Description
addNode(node)	Add a node (parent folders auto-created from path)
removeNode(path)	Remove a node and its descendants
renameNode(path, newName)	Rename a node (changes only the last path segment)
moveNode(sourcePath, targetParentPath)	Move a node to a new parent folder ('' or null for root)
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	A node is selected
expand	A folder is expanded
collapse	A folder is collapsed
create	A new node is created (after name is committed)
rename	A node is renamed
delete	A node is deleted
move	A node is moved via drag-and-drop or API
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;
  node: FileTreeNodeData; // The affected node
  path: string; // Current path (same as node.path)
  oldPath?: string; // Previous path (rename/move)
  parentPath: string; // Parent folder path ('' for root)
  parentNode: FileTreeNodeData | null;
  tree: FileTreeNodeData[]; // Full flat data snapshot
  data?: { files: FileList; items: DataTransferItemList }; // Drag-and-drop
}

Keyboard Shortcuts

Key	Action
↑ / ↓	Navigate between visible nodes
→	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

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";

Browser Support

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

License

MIT