folder-tree: Tree View with Search, DnD, and Checkboxes

folder-tree is a zero-dependency TypeScript tree view library for rendering and managing hierarchical data on a web page.

It accepts nested JSON, flat parent-based data, AJAX responses, lazy-loading callbacks, or existing HTML.

Optional plugins handle search, checkboxes, drag and drop, context menus, sorting, state persistence, node types, and other tree interactions.

Features

• Nested and flat JSON tree data.
• AJAX and callback-based lazy loading.
• Search with filtering and fuzzy matching.
• Checkbox selection with three-state cascading.
• Drag and drop with move and copy operations.
• Context menus with custom items and submenus.
• Node types with icons and structural rules.
• Child-node sorting with custom comparators.
• Tree state persistence through localStorage.
• Keyboard navigation and configurable shortcuts.
• ESM, CommonJS, and UMD builds.
• TypeScript declarations included.
• Custom plugin registration.
• Native DOM events.

How To Use It

Installation

Install the package with npm:

npm install @mdaemon/folder-tree

Import the tree class and stylesheet:

import { MDFolderTree } from '@mdaemon/folder-tree';
import '@mdaemon/folder-tree/styles.css';

Basic Usage

Create a container for the tree view:

<div id="folder-tree"></div>

Initialize the tree with hierarchical data:

const element = document.getElementById('folder-tree');
const tree = new MDFolderTree(element, {
  core: {
    data: [
      {
        id: 'documents',
        text: 'Documents',
        children: [
          {
            id: 'reports',
            text: 'Reports'
          },
          {
            id: 'invoices',
            text: 'Invoices'
          }
        ]
      },
      {
        id: 'downloads',
        text: 'Downloads'
      }
    ]
  }
});

Browser Build

The UMD build exposes MDFolderTree and mdTree() globally.

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@mdaemon/folder-tree/dist/styles.css"
>
<div id="folder-tree"></div>
<script src="https://cdn.jsdelivr.net/npm/@mdaemon/folder-tree/dist/MDFolderTree.umd.js"></script>
<script>
const tree = new MDFolderTree(
  document.getElementById('folder-tree'),
  {
    core: {
      data: [
        {
          id: 'projects',
          text: 'Projects',
          children: [
            { id: 'frontend', text: 'Frontend' },
            { id: 'backend', text: 'Backend' }
          ]
        }
      ]
    }
  }
);
</script>

Loading Tree Data

Nested JSON

const tree = new MDFolderTree(element, {
  core: {
    data: [
      {
        id: 'projects',
        text: 'Projects',
        children: [
          {
            id: 'frontend',
            text: 'Frontend',
            children: [
              {
                id: 'components',
                text: 'Components'
              }
            ]
          }
        ]
      }
    ]
  }
});

Flat JSON

Flat arrays can use parent references:

const tree = new MDFolderTree(element, {
  core: {
    data: [
      { id: '1', text: 'Projects', parent: '#' },
      { id: '2', text: 'Frontend', parent: '1' },
      { id: '3', text: 'Components', parent: '2' }
    ]
  }
});

Lazy Loading

Use a core.data callback to load child nodes when a branch opens:

const tree = new MDFolderTree(element, {
  core: {
    data(node, callback) {
      fetch(`/api/tree/${encodeURIComponent(node.id)}`)
        .then(response => response.json())
        .then(callback);
    }
  }
});

AJAX Data

core.data also accepts an AJAX configuration object:

const tree = new MDFolderTree(element, {
  core: {
    data: {
      url(node) {
        return `/api/tree/${encodeURIComponent(node.id)}`;
      },
      type: 'GET',
      dataType: 'json',
      headers: {
        Accept: 'application/json'
      }
    }
  }
});

Existing HTML

The tree can read nested <ul> and <li> markup:

<div id="folder-tree">
  <ul>
    <li id="projects">
      <a>Projects</a>
      <ul>
        <li id="frontend">
          <a>Frontend</a>
        </li>
      </ul>
    </li>
  </ul>
</div>

Initialize the existing markup:

const tree = new MDFolderTree(
  document.getElementById('folder-tree')
);

Built-in Plugins

Plugins are enabled through the plugins array.

const tree = new MDFolderTree(element, {
  core: {
    data
  },
  plugins: [
    'types',
    'checkbox',
    'search',
    'contextmenu',
    'dnd'
  ]
});

Checkboxes

Enable the checkbox plugin:

const tree = new MDFolderTree(element, {
  core: {
    data
  },
  checkbox: {
    three_state: true,
    tie_selection: false
  },
  plugins: ['checkbox']
});

Search

Enable the search plugin:

const tree = new MDFolderTree(element, {
  core: {
    data
  },
  search: {
    show_only_matches: true,
    fuzzy: true
  },
  plugins: ['search']
});
tree.search('invoice');

Clear the search:

tree.clear_search();

Drag And Drop

Enable drag and drop and permit structural changes through core.check_callback:

const tree = new MDFolderTree(element, {
  core: {
    data,
    check_callback: true
  },
  dnd: {
    copy: true,
    drag_selection: true
  },
  plugins: ['dnd']
});

Context Menus

Enable the default context menu:

const tree = new MDFolderTree(element, {
  core: {
    data,
    check_callback: true
  },
  plugins: ['contextmenu']
});

Custom menu items can replace the defaults:

const tree = new MDFolderTree(element, {
  core: {
    data
  },
  contextmenu: {
    items(node) {
      return {
        open: {
          label: 'Open',
          action() {
            console.log(node.id);
          }
        }
      };
    }
  },
  plugins: ['contextmenu']
});

Node Types

The types plugin can assign icons and structural restrictions:

const tree = new MDFolderTree(element, {
  core: {
    data
  },
  types: {
    default: {
      icon: 'md-tree-folder'
    },
    file: {
      icon: 'md-tree-file',
      max_children: 0
    }
  },
  plugins: ['types']
});

Sorting

The sort callback receives two node IDs and uses the tree instance as this:

const tree = new MDFolderTree(element, {
  core: {
    data
  },
  sort(a, b) {
    return this.get_text(a).localeCompare(
      this.get_text(b)
    );
  },
  plugins: ['sort']
});

State Persistence

Enable the state plugin to store open, selected, and related tree state in localStorage:

const tree = new MDFolderTree(element, {
  core: {
    data
  },
  state: {
    key: 'project-tree',
    ttl: 86400000
  },
  plugins: ['state']
});

Node Data Reference

Each JSON node can use these public fields:

• id (string): Node ID.
• text (string): Node label.
• icon (string | boolean | null): Icon class list, image URL, default theme icon, or hidden icon.
• type (string): Node type used by the types plugin.
• children (TreeNodeData[] | boolean): Nested children or lazy-load state.
• state (object): Initial node state.
• li_attr (Record<string, string>): Attributes applied to the node <li>.
• a_attr (Record<string, string>): Attributes applied to the node anchor.
• data (Record<string, unknown> | false | null): Application data attached to the node.
• parent (string in flat arrays): Parent node ID. Use # for a root node.

Node State

The public node state accepts:

• opened (boolean): Starts the node open.
• selected (boolean): Starts the node selected.
• disabled (boolean): Starts the node disabled.
• checked (boolean): Starts the node checked when checkbox state is independent from selection.
• loaded (boolean): Marks a node as loaded.

All Configuration Options

Top-Level Configuration

• core (CoreConfig): Core data, loading, selection, themes, keyboard behavior, and structural validation.
• types (Record<string, TypeConfig>): Node types and type rules.
• checkbox (CheckboxConfig): Checkbox behavior.
• search (SearchConfig): Search behavior.
• contextmenu (ContextMenuConfig): Context menu settings.
• dnd (DndConfig): Drag-and-drop settings.
• massload (MassloadCallback | AjaxConfig | null): Batched node loading.
• sort (SortComparator): Child-node sorting callback.
• state (StateConfig): State persistence settings.
• unique (UniqueConfig): Duplicate sibling-name rules.
• conditionalselect (ConditionalSelectCallback): Node activation callback.
• plugins (string[], default []): Enabled plugin names.

Core Options

• data (TreeNodeData[] | DataCallback | AjaxConfig | string | false, default false): Tree data source.
• multiple (boolean, default true): Permits multi-selection through user interaction.
• animation (number, default 200): Open and close animation duration in milliseconds.
• themes (ThemeConfig): Theme settings.
• check_callback (boolean | function | object, default false): Controls create, rename, delete, move, copy, and edit operations.
• expand_selected_onload (boolean, default true): Opens ancestors of selected nodes before the initial ready event.
• force_text (boolean, default false): Forces node labels to render as text.
• dblclick_toggle (boolean, default true): Toggles branches on double click.
• compute_elements_positions (boolean, default false): Writes aria-setsize and aria-posinset values on rendered nodes.
• worker (boolean, default true): Uses a Web Worker for transferable JSON data.
• strings (Record<string, string> | function): Replaces built-in UI strings.
• error (function): Receives tree error objects.
• loaded_state (boolean, default false): Includes loaded node IDs in tree state.
• restore_focus (boolean, default true): Restores focus to the previously focused node.
• allow_reselect (boolean, default false): Re-runs selection behavior for an already selected node.
• keyboard (Record<string, KeyboardHandler | null> | boolean): Customizes keyboard shortcuts. false disables all shortcuts.
• sanitize_attrs (boolean, default true): Removes inline on* attributes from li_attr and a_attr.

Keyboard Defaults

The default keyboard controls include:

• ctrl+space
• enter
• Arrow keys
• *
• home
• end
• f2

Theme Options

• name (string | false, default default): Theme name.
• url (string | boolean, default false): Theme stylesheet URL.
• dir (string | false): Base directory used when url is true.
• dots (boolean, default true): Shows connector dots.
• icons (boolean, default true): Shows node icons.
• ellipsis (boolean, default false): Enables ellipsis styling for long labels.
• stripes (boolean, default false): Enables striped rows.
• variant (string | false, default false): Theme variant.
• responsive (boolean, default false): Applies the responsive theme class.

Type Options

• icon (string | boolean): Node icon.
• max_children (number, default -1): Maximum direct children.
• max_depth (number, default -1): Maximum descendant depth.
• valid_children (number | string[], default -1): Accepted child types.
• li_attr (Record<string, string>): Attributes merged into the <li>.
• a_attr (Record<string, string>): Attributes merged into the anchor.

Checkbox Options

• keep_selected_style (boolean, default true): Keeps selected-node styling.
• visible (boolean, default true): Controls checkbox visibility.
• three_state (boolean, default true): Enables upward, downward, and undetermined cascading.
• cascade (string, default "" when three_state is false): Sets explicit cascade directions.
• tie_selection (boolean, default true): Uses selection state as checkbox state.
• whole_node (boolean, default true): Lets the node label toggle the checkbox.
• cascade_to_disabled (boolean, default true): Includes disabled nodes in cascading.
• cascade_to_hidden (boolean, default true): Includes hidden nodes in cascading.

Search Options

• show_only_matches (boolean, default false): Hides nonmatching branches outside the required ancestry.
• show_only_matches_children (boolean, default false): Keeps descendants of matching nodes visible.
• close_opened_onclear (boolean, default true): Closes branches opened by a search after clearing it.
• case_sensitive (boolean, default false): Enables case-sensitive matching.
• fuzzy (boolean, default false): Enables approximate matching for patterns up to 32 characters.
• search_leaves_only (boolean, default false): Restricts matches to loaded leaf nodes.
• search_callback (function): Replaces the built-in matcher.
• ajax (false | AjaxConfig | function): Loads nodes required before a search.

AJAX Options

The AJAX object used by core.data, search.ajax, and massload accepts:

• url (string | function, required): Request URL.
• data: Request data.
• type (string): HTTP method.
• method (string): HTTP method.
• dataType (string): Expected response type.
• contentType (string | false): Request content type.
• headers (Record<string, string>): Request headers.
• cache (boolean): Request cache setting.
• xhrFields.withCredentials (boolean): Sends credentials with the request.

Context Menu Options

• select_node (boolean, default true): Activates an unselected node before opening the menu.
• show_at_node (boolean, default true): Positions the menu at the node.
• items (object | function): Menu item definitions or generator callback.

Context Menu Item Options

• label (string | function): Item label.
• title (string): Title text.
• icon (string | false): Icon class list or image URL.
• action (false | function): Item handler.
• separator_before (boolean): Separator before the item.
• separator_after (boolean): Separator after the item.
• _disabled (boolean | function): Disabled state.
• _class (string): Item classes.
• shortcut (number): Keyboard shortcut code.
• shortcut_label (string): Shortcut label.
• submenu (Record<string, ContextMenuItem>): Nested items.

Drag And Drop Options

• copy (boolean, default true): Lets Ctrl or Meta switch a drag from move to copy.
• open_timeout (number, default 500): Delay before opening a hovered closed node.
• is_draggable (boolean | function, default true): Controls which nodes can start a drag.
• check_while_dragging (boolean): Runs structural checks during dragging.
• always_copy (boolean, default false): Copies every accepted drop.
• inside_pos (number | "first" | "last", default 0): Child position for inside drops.
• drag_selection (boolean, default true): Drags the top selected nodes when the grabbed node belongs to the selection.
• touch (boolean | "selected"): Controls touch dragging.
• large_drop_target (boolean): Uses the full node as the drop area.
• large_drag_target (boolean | string): Expands the draggable area.
• use_html5 (boolean, default false): Uses native HTML5 drag and drop.
• blank_space_drop (boolean, default false): Accepts root-level drops on empty tree space.

Massload

massload accepts a callback or AJAX configuration.

const tree = new MDFolderTree(element, {
  core: {
    data(node, callback) {
      fetch(`/api/tree/${node.id}`)
        .then(response => response.json())
        .then(callback);
    }
  },
  massload(ids, callback) {
    fetch(
      `/api/tree/batch?ids=${encodeURIComponent(ids.join(','))}`
    )
      .then(response => response.json())
      .then(callback);
  },
  plugins: ['massload']
});

State Options

• key (string, default jstree): localStorage key.
• events (string): Events that schedule a state save.
• ttl (number | false, default false): Saved-state lifetime in milliseconds.
• filter (function): Adjusts state before restoration.
• preserve_loaded (boolean, default false): Keeps core.loaded in stored state.

Default event string:

changed.MDFolderTree open_node.MDFolderTree close_node.MDFolderTree check_node.MDFolderTree uncheck_node.MDFolderTree

Unique Options

• case_sensitive (boolean, default false): Uses case-sensitive sibling-name comparison.
• trim_whitespace (boolean, default false): Trims surrounding whitespace before comparison.
• duplicate (function): Generates a replacement name for automatically created duplicates.

The default duplicate pattern uses:

Name (2)
Name (3)
Name (4)

Conditional Selection

conditionalselect receives the node and activation event:

const tree = new MDFolderTree(element, {
  core: {
    data
  },
  conditionalselect(node) {
    return node.type !== 'readonly';
  },
  plugins: ['conditional_select']
});

Public API

Constructor

const tree = new MDFolderTree(element, config);

• element (HTMLElement): Tree container.
• config (TreeConfig, optional): Tree configuration.

Instance Helpers

• MDFolderTree.getInstance(element): Returns the tree instance attached to an element or null.
• MDFolderTree.registerPlugin(name, factory): Registers a plugin factory.
• tree.getPlugin(name): Returns an active plugin instance or null.

Node Lookup And Selection

get_json() Options

• flat: Returns a flat list with parent fields.
• no_state: Omits state.
• no_id: Omits node IDs and ID attributes.
• no_children: Omits children.
• no_data: Returns data: false.
• no_li_attr: Omits <li> attributes.
• no_a_attr: Omits anchor attributes.

Opening And Closing

Loading And Rendering

Enable, Disable, Show, And Hide

Creating And Editing Nodes

Structural changes require an accepting core.check_callback.

Accepted position values include numeric indexes plus:

• first
• inside
• last
• before
• after

Checkbox Methods

Search Methods

search() uses this signature:

tree.search(
  query,
  skipAsync,
  showOnlyMatches,
  inside,
  append,
  showOnlyMatchesChildren
);

• search(...): Runs a tree search and returns matching IDs.
• clear_search(): Clears the current search.

Theme Methods

Icon Methods

Type And Sort Methods

State Methods

The state plugin also exposes:

• save_state()
• restore_state()
• clear_state()

Access them through:

const statePlugin = tree.getPlugin('state');

Clipboard Methods

Container And Event Methods

Events

Tree events use the .MDFolderTree namespace.

Lifecycle And Data Events

Selection Events

Open And Close Events

Node Mutation Events

Visibility Events

Checkbox Events

When checkbox.tie_selection is true, check operations use selection events.

Search Events

Drag And Drop Events

State Events

Clipboard Events

Theme Events

Context Menu Events

• show_contextmenu.MDFolderTree: Fires when a node context menu opens.
• context_show.vakata: Fires on document when the menu opens.
• context_hide.vakata: Fires on document when the menu closes.

Custom Plugins

Register a plugin factory before creating a tree that uses it:

MDFolderTree.registerPlugin('audit', () => ({
  name: 'audit',
  init(tree) {
    tree.on(
      'select_node.MDFolderTree',
      function (event) {
        console.log(
          'Selected:',
          event.detail.node.id
        );
      }
    );
  },
  destroy() {}
}));
const tree = new MDFolderTree(element, {
  core: {
    data
  },
  plugins: ['audit']
});

Plugin Hooks

A custom TreePlugin can implement:

• init(tree)
• destroy()
• onNodeRender(node, element)
• onBeforeRender(nodes)
• onBeforeActivate(node, event)
• onCheck(chk, node, parent, pos, more)

TreePluginHost API

The plugin host exposes:

• config
• getNode(id)
• getAllNodes()
• getNodeChildren(id)
• getSelectedIds()
• getOpenedIds()
• selectNode(id, suppress?, preventOpen?, event?)
• deselectNode(id, suppress?, event?)
• applySelection(ids, selected)
• selectAll(suppress?)
• deselectAll(suppress?)
• openNode(id, suppress?, animation?)
• closeNode(id, suppress?, animation?)
• getContainer()
• on(event, handler)
• off(event, handler)
• emit(event, detail)
• redrawNode(id)
• redraw()
• moveNode(id, parentId, position)
• copyNode(id, parentId, position)
• renameNode(id, text)
• deleteNode(id)
• createNode(parentId, data, position?)
• reorderChildren(parentId, childIds)
• setChildOrder(parentId, childIds)
• getRootNodeIds()

Migrating From jstree

folder-tree keeps familiar jstree configuration groups, node formats, plugin names, and many method signatures. Migration mainly affects initialization, events, CSS prefixes, and the tree data attribute.

Replace $.jstree() Calls

Import mdTree:

import { mdTree } from '@mdaemon/folder-tree';

Create a tree:

// jstree
$('#tree').jstree({
  core: {
    data
  }
});
// folder-tree
mdTree('#tree', {
  core: {
    data
  }
});

Retrieve the current instance:

const tree = mdTree('#tree', true);

Call an instance method:

mdTree('#tree', 'select_node', 'node-1');

mdTree() Signatures

• mdTree(element): Creates a default tree or returns the existing instance.
• mdTree(element, config): Creates a configured tree or returns the existing instance.
• mdTree(element, true): Returns the existing instance.
• mdTree(element, 'method', ...args): Calls an instance method.

CSS Class Migration

Data Attribute Migration

Change data-jstree to data-md-tree:

<li
  id="folder-1"
  class="md-tree-open"
  data-md-tree='{"type":"folder","opened":true}'
>
  <a>Folder 1</a>
</li>

Event Migration

Replace jQuery event handlers with native DOM listeners:

document
  .getElementById('tree')
  .addEventListener(
    'changed.MDFolderTree',
    function (event) {
      console.log(event.detail.selected);
    }
  );

Automated Migration Script

The package includes a script for scanning and applying common migration changes:

node node_modules/@mdaemon/folder-tree/scripts/migrate-from-jstree.mjs ./src

Styling

The main structural CSS uses the md-tree prefix. Project-specific node classes can be attached through:

• li_attr.class
• a_attr.class
• types[type].li_attr
• types[type].a_attr

Alternatives And Related Resources

• 10 Best Tree View JavaScript Libraries in 2026 (Lightweight & Free)
• JavaScript Tree/TreeGrid with Drag, Edit & Filter – Wunderbaum
• Dynamic Interactive Tree View With Checkboxes – Treejs
• JavaScript Treeview Library for Hierarchical Data – Quercus.js
• Visualize Your Project Structure With The file-tree Component