# react-virtual-checkbox-tree > Headless, virtualized checkbox tree for React. Tri-state parents that stay correct at 100,000 nodes, ancestor-aware search, full keyboard navigation, and no CSS you didn't write. Version 0.2.0 (0.x — the API will change before 1.0). MIT licensed. Install with `npm install react-virtual-checkbox-tree`. Requires React 18 or 19. Two entry points: `react-virtual-checkbox-tree` ships the React component with a "use client" banner, and `react-virtual-checkbox-tree/engine` ships the headless core with no React and no virtualizer in the bundle. Known non-goals, stated up front so they are not mistaken for gaps in these docs: there is no drag-and-drop, no inline rename, no context menus, no `onLoadChildren` for lazy children, no checkable folders and no `checkStrictly` mode, and graphs are not supported (a node under two parents keeps only the last parent seen). ## Getting started - [Introduction](https://react-virtual-checkbox-tree.vercel.app/docs): What this library is, what it refuses to do, and why it exists. - [Installation](https://react-virtual-checkbox-tree.vercel.app/docs/installation): Install, peer dependencies, and framework notes for Next.js, Vite and Remix. - [Quick start](https://react-virtual-checkbox-tree.vercel.app/docs/quick-start): A complete working tree in one file. ## Core concepts - [Data model](https://react-virtual-checkbox-tree.vercel.app/docs/data-model): TreeDefinition, the `__root__` node, and why the map is flat. - [Checkbox semantics](https://react-virtual-checkbox-tree.vercel.app/docs/checkbox-semantics): Tri-state, leaf-only checking, and how cascades are stored sparsely. - [Controlled & uncontrolled](https://react-virtual-checkbox-tree.vercel.app/docs/controlled-uncontrolled): Taking control of selection, expansion and search independently. - [Search](https://react-virtual-checkbox-tree.vercel.app/docs/search): Ancestor-aware filtering, diacritics, and visible-leaf-only toggling. - [Virtualization](https://react-virtual-checkbox-tree.vercel.app/docs/virtualization): Row heights, overscan, scroll containers, and what actually mounts. ## Customization - [Render props](https://react-virtual-checkbox-tree.vercel.app/docs/rendering): renderItem, renderCheckbox and renderExpander. - [Styling](https://react-virtual-checkbox-tree.vercel.app/docs/styling): Data attributes, a Tailwind skin, and a shadcn/ui checkbox recipe. - [Imperative API](https://react-virtual-checkbox-tree.vercel.app/docs/imperative-api): expandAll, collapseAll, scrollToId, focusId and getEngine. ## Reference - [`` props](https://react-virtual-checkbox-tree.vercel.app/docs/api/tree): Every prop, its default, and its exact semantics. - [Engine](https://react-virtual-checkbox-tree.vercel.app/docs/api/engine): The headless core: every method on the class. - [Types](https://react-virtual-checkbox-tree.vercel.app/docs/api/types): TreeDefinition, TreeItem, VisibleItem, CheckedState and the render props. - [Accessibility](https://react-virtual-checkbox-tree.vercel.app/docs/accessibility): The ARIA tree contract, every keyboard shortcut, and known gaps. - [Performance](https://react-virtual-checkbox-tree.vercel.app/docs/performance): Measured numbers, where the time goes, and how to go faster. ## Guides - [From react-checkbox-tree](https://react-virtual-checkbox-tree.vercel.app/docs/migrating/react-checkbox-tree): A prop-by-prop migration map. - [Persist a selection](https://react-virtual-checkbox-tree.vercel.app/docs/recipes/persist-selection): Storing selection sparsely instead of as a list of every leaf. - [Loading data in pages](https://react-virtual-checkbox-tree.vercel.app/docs/recipes/async-children): Growing the tree as results arrive without losing state. - [FAQ](https://react-virtual-checkbox-tree.vercel.app/docs/faq): The questions people actually ask before installing. ## Interactive - [Playground](https://react-virtual-checkbox-tree.vercel.app/playground): Generate up to 100,000 nodes and drive the real component. - [Examples](https://react-virtual-checkbox-tree.vercel.app/examples): Six complete, copyable implementations. - [File picker](https://react-virtual-checkbox-tree.vercel.app/examples/file-picker): Select files across nested folders. - [Permissions matrix](https://react-virtual-checkbox-tree.vercel.app/examples/permissions-matrix): Where the indeterminate state is the product. - [shadcn/ui styled](https://react-virtual-checkbox-tree.vercel.app/examples/shadcn-styled): Drop in the Radix checkbox and Lucide icons. - [Faceted filter](https://react-virtual-checkbox-tree.vercel.app/examples/faceted-filter): A deep category tree wired to the URL. - [Engine only](https://react-virtual-checkbox-tree.vercel.app/examples/engine-only): The headless core with a hand-written renderer. - [Paged loading](https://react-virtual-checkbox-tree.vercel.app/examples/async-pages): Grow the tree as API pages arrive. ## Comparisons - [Compare](https://react-virtual-checkbox-tree.vercel.app/compare): How this library differs from the alternatives. - [react-checkbox-tree](https://react-virtual-checkbox-tree.vercel.app/compare/react-checkbox-tree): The incumbent. Same mental model, no virtualization path. - [react-arborist](https://react-virtual-checkbox-tree.vercel.app/compare/react-arborist): Virtualized and excellent, but has no checkboxes. - [headless-tree](https://react-virtual-checkbox-tree.vercel.app/compare/headless-tree): Same philosophy, wider scope — and virtualization is your job. - [MUI X Rich Tree View](https://react-virtual-checkbox-tree.vercel.app/compare/mui-x-tree-view): Virtualization is behind the Pro licence. - [rc-tree / antd Tree](https://react-virtual-checkbox-tree.vercel.app/compare/rc-tree): Genuinely virtualized, if you want an Ant-shaped API. - [Writing it yourself](https://react-virtual-checkbox-tree.vercel.app/compare/writing-it-yourself): The real competitor. The four bugs you will write. ## Optional - [llms-full.txt](https://react-virtual-checkbox-tree.vercel.app/llms-full.txt): Every documentation page concatenated into one plain-text file. - [GitHub](https://github.com/jadghadry/react-virtual-checkbox-tree): source, issues and the benchmark script. - [npm](https://www.npmjs.com/package/react-virtual-checkbox-tree): published package and version history.