Engine

// Pulls in React and @tanstack/react-virtual, and carries a "use client" banner.
import { Engine } from "react-virtual-checkbox-tree";

// No React, no virtualizer, no "use client" — safe in a Server Component or a Node script.
import { Engine } from "react-virtual-checkbox-tree/engine";

import {
  CheckedState,
  Engine,
  ROOT_ID,
  type EngineOptions,
  type TreeDefinition,
} from "react-virtual-checkbox-tree/engine";

const fileTree: TreeDefinition = {
  __root__: { id: "__root__", label: "root", children: ["docs", "src"] },
  docs: { id: "docs", label: "docs", children: ["readme", "guide"] },
  readme: { id: "readme", label: "README.md" },
  guide: { id: "guide", label: "guide.md" },
  src: { id: "src", label: "src", children: ["engine", "ui"] },
  engine: { id: "engine", label: "engine.ts" },
  ui: { id: "ui", label: "ui", children: ["tree", "row"] },
  tree: { id: "tree", label: "tree.tsx" },
  row: { id: "row", label: "row.tsx" },
};

const options: EngineOptions = {
  initialExpanded: ["src", "ui"],
  minSearchChars: 3,
  rootId: ROOT_ID,
  searchScope: "all",
};

const engine = new Engine(fileTree, options);

const unsubscribe = engine.subscribe(() => {
  console.log(engine.getVisibleItems().length, "rows");
});

engine.toggle("src", true);
engine.getViewState("ui") === CheckedState.Checked; // true
engine.getAllChecked().sort(); // ["engine", "row", "tree"] — leaves only

unsubscribe();

new Engine(data: TreeDefinition, opts?: EngineOptions)

import {
  CheckedState,
  Engine,
  type TreeDefinition,
} from "react-virtual-checkbox-tree/engine";

const fileTree: TreeDefinition = {
  __root__: { id: "__root__", label: "root", children: ["docs", "src"] },
  docs: { id: "docs", label: "docs", children: ["readme", "guide"] },
  readme: { id: "readme", label: "README.md" },
  guide: { id: "guide", label: "guide.md" },
  src: { id: "src", label: "src", children: ["engine", "ui"] },
  engine: { id: "engine", label: "engine.ts" },
  ui: { id: "ui", label: "ui", children: ["tree", "row"] },
  tree: { id: "tree", label: "tree.tsx" },
  row: { id: "row", label: "row.tsx" },
};

const engine = new Engine(fileTree, { initialExpanded: ["src", "ui"] });

const GLYPH = {
  [CheckedState.Checked]: "[x]",
  [CheckedState.Indeterminate]: "[-]",
  [CheckedState.Unchecked]: "[ ]",
};

function print() {
  for (const row of engine.getVisibleItems()) {
    const indent = "  ".repeat(row.level);
    const arrow = row.isFolder ? (row.isExpanded ? "v " : "> ") : "  ";
    console.log(`${indent}${arrow}${GLYPH[engine.getViewState(row.id)]} ${engine.getLabel(row.id)}`);
  }
  console.log("---");
}

// Re-render on every change, exactly like a UI would.
engine.subscribe(print);

engine.toggle("ui", true);
// > [ ] docs
// v [-] src
//     [ ] engine.ts
//   v [x] ui
//       [x] tree.tsx
//       [x] row.tsx
// ---

console.log(engine.getAllChecked().sort()); // ["row", "tree"]
console.log(engine.getState("src")); // "indeterminate"
console.log(engine.getNodeCount(), engine.getLeafCount()); // 8 5

engine.setSearchQuery("tree");
console.log(engine.getMatchCount()); // 1
console.log(engine.getVisibleItems().map((row) => row.id)); // ["src", "ui", "tree"]

engine.setSearchQuery("");
console.log(engine.isSearchActive()); // false

import { Engine, type TreeDefinition } from "react-virtual-checkbox-tree/engine";

const fileTree: TreeDefinition = {
  __root__: { id: "__root__", label: "root", children: ["docs", "src"] },
  docs: { id: "docs", label: "docs", children: ["readme", "guide"] },
  readme: { id: "readme", label: "README.md" },
  guide: { id: "guide", label: "guide.md" },
  src: { id: "src", label: "src", children: ["engine", "ui"] },
  engine: { id: "engine", label: "engine.ts" },
  ui: { id: "ui", label: "ui", children: ["tree", "row"] },
  tree: { id: "tree", label: "tree.tsx" },
  row: { id: "row", label: "row.tsx" },
};

const engine = new Engine(fileTree);
engine.toggle("src", true);
engine.toggle("engine", false);

// Two entries describe a selection that getAllChecked() spells out as a list.
const sparse = engine.getCheckedSubtrees();
// [{ checked: true, id: "src" }, { checked: false, id: "engine" }]
localStorage.setItem("selection", JSON.stringify(sparse));

// Later, in another session:
const restored = new Engine(fileTree);
restored.setCheckedSubtrees(JSON.parse(localStorage.getItem("selection") ?? "[]"));
restored.getAllChecked().sort(); // ["row", "tree"]

import { useEffect, useRef, useState } from "react";
import { Tree, type TreeDefinition, type TreeRef } from "react-virtual-checkbox-tree";

const fileTree: TreeDefinition = {
  __root__: { id: "__root__", label: "root", children: ["docs", "src"] },
  docs: { id: "docs", label: "docs", children: ["readme", "guide"] },
  readme: { id: "readme", label: "README.md" },
  guide: { id: "guide", label: "guide.md" },
  src: { id: "src", label: "src", children: ["engine", "ui"] },
  engine: { id: "engine", label: "engine.ts" },
  ui: { id: "ui", label: "ui", children: ["tree", "row"] },
  tree: { id: "tree", label: "tree.tsx" },
  row: { id: "row", label: "row.tsx" },
};

export function WithLiveCount() {
  const treeRef = useRef<TreeRef>(null);
  const [count, setCount] = useState(0);

  useEffect(() => {
    const engine = treeRef.current?.getEngine();
    if (!engine) return;
    // subscribe() returns its own unsubscribe function.
    return engine.subscribe(() => setCount(engine.getAllChecked().length));
  }, []);

  return (
    <>
      <p>{count} files selected</p>
      <Tree aria-label="Project files" data={fileTree} height={320} ref={treeRef} />
    </>
  );
}