react-virtual-checkbox-tree vs react-checkbox-tree

These two libraries have the same mental model: a tree of nodes, leaf-only checked values, a parent that goes indeterminate when its children disagree, controlled checked and expanded arrays. If you already know react-checkbox-tree you already know this one, and the migration guide is a prop-by-prop table rather than a rewrite.

What differs is everything below the API: rows are virtualized, the cascade is stored sparsely instead of as an array of every checked value, there is a real role="tree" with arrow-key navigation, and there is no stylesheet.

What react-checkbox-tree does better

Quite a lot, and some of it is not on any roadmap here.

What changes if you switch

The data goes flat

The single real migration cost. react-checkbox-tree takes a nested array of { value, label, children }; this takes a flat map keyed by ID with a __root__ entry. Lookups become O(1), IDs stay stable across updates, and you can build the map straight out of a SQL result — but you do have to convert.

// npm i react-checkbox-tree
import { useState } from "react";
import CheckboxTree from "react-checkbox-tree";
import "react-checkbox-tree/lib/react-checkbox-tree.css";

const nodes = [
  {
    value: "docs",
    label: "docs",
    children: [
      { value: "readme", label: "README.md" },
      { value: "guide", label: "guide.md" },
    ],
  },
  {
    value: "src",
    label: "src",
    children: [
      { value: "engine", label: "engine.ts" },
      {
        value: "ui",
        label: "ui",
        children: [
          { value: "tree", label: "tree.tsx" },
          { value: "row", label: "row.tsx" },
        ],
      },
    ],
  },
];

export default function App() {
  const [checked, setChecked] = useState<string[]>([]);
  const [expanded, setExpanded] = useState<string[]>(["src"]);

  return (
    <CheckboxTree
      checked={checked}
      expanded={expanded}
      nodes={nodes}
      onCheck={setChecked}
      onExpand={setExpanded}
    />
  );
}

// npm i react-virtual-checkbox-tree
import { useState } from "react";
import { Tree, type TreeDefinition } from "react-virtual-checkbox-tree";

// Same tree, flat instead of nested. Keys are IDs; "__root__" holds the top level.
const data: 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 default function App() {
  const [checked, setChecked] = useState<string[]>([]);
  const [expanded, setExpanded] = useState<string[]>(["src"]);

  return (
    <Tree
      aria-label="Project files"
      checkedItems={checked}
      data={data}
      expandedItems={expanded}
      height={320}
      onCheck={setChecked}
      onExpand={setExpanded}
    />
  );
}

If your data arrives nested from an API, convert it once:

// Nested -> flat, once, at the edge of your app.
import type { TreeDefinition, TreeItem } from "react-virtual-checkbox-tree";

type LegacyNode = { children?: LegacyNode[]; label: string; value: string };

export function flatten(nodes: LegacyNode[]): TreeDefinition {
  const data: TreeDefinition = {
    __root__: { id: "__root__", label: "root", children: nodes.map((n) => n.value) },
  };

  const walk = (node: LegacyNode) => {
    const item: TreeItem = { id: node.value, label: node.label };
    if (node.children?.length) {
      item.children = node.children.map((child) => child.value);
      node.children.forEach(walk);
    }
    data[node.value] = item;
  };

  nodes.forEach(walk);
  return data;
}

The stylesheet goes away

There is no react-virtual-checkbox-tree/lib/*.css to import, because the library ships no stylesheet. The only styles it sets are the inline ones virtualization requires — the absolutely positioned row, its height, and the indent. Everything visual is yours. Rows carry data-rvct-row, data-state ("checked" / "unchecked" / "indeterminate"), data-level, data-expanded, data-leaf and data-active, and you style those. If you liked the Font Awesome look you will have to rebuild it; see Styling.

onCheck changes shape

react-checkbox-tree calls onCheck(checked, targetNode). This calls onCheck(checkedLeafIds) — one argument, always leaf IDs, never folders. If you were using checkModel="all" there is no equivalent and you will need to derive the folder set yourself from the leaf IDs.

Keyboard and screen readers start working

react-checkbox-tree toggles on Space and Enter via its checkKeys prop, and that is the extent of it: there are no arrow keys, and issue #280 (“Checkbox tree is not accessible through keyboard”) has been open since 2021. This library implements the WAI-ARIA tree pattern: role="tree" with aria-multiselectable, role="treeitem" with aria-level, aria-setsize, aria-posinset and aria-checked="mixed", plus ArrowUp/Down/Left/Right, Home, End, Space, Enter, * to expand everything, Ctrl/Cmd+A, and type-ahead. Focus is tracked with aria-activedescendant on the container, so a row being unmounted by the virtualizer can never take the focus with it.

How much does the virtualization actually buy?

Below roughly 2,000 nodes: nothing you will notice. react-checkbox-tree flattens its source tree into a map internally and memoizes, and it is not a slow library — it is an unvirtualized one, which is a different problem. The cost is DOM: every node is an element, every check re-renders the subtree, and every value lands in a checked array that grows with the selection.

Here the DOM holds a window of rows regardless of tree size, and the selection is stored as sparse assignments rather than a list — checking a folder of 50,000 leaves writes one map entry. These are measured, on the published build, with npm run bench:

The honest column is the middle one. Asking for the full list of checked leaf IDs has to materialize that list, and at 111,110 nodes that is 3.7 ms per change. At that scale you read getCheckedSubtrees() instead — the sparse form — which is what Persist a selection is about. Building the engine is also linear: 115 ms at 111,110 nodes, about two seconds at a million.

Should you migrate?

Probably not, if it currently works. A working react-checkbox-tree with 400 nodes in it is not a problem you have. Migrate when the tree got big enough that opening the panel janks, when an accessibility audit came back, or when you need search that filters rather than highlights.