React Checkbox Tree

2.0.1 · active · verified Sun Apr 19

react-checkbox-tree is a React component designed to render a hierarchical tree of checkboxes. It provides a simple and elegant solution for implementing multi-select functionality with nested options. Currently stable at version 2.0.1, released in April 2026, the library recently underwent a major accessibility-focused overhaul in its 2.0.0 release. While its release cadence has historically varied, with a significant gap before the v2.x releases, the recent activity suggests ongoing development. Key differentiators include its controlled component architecture, support for customizable icons (including Font Awesome v4, v5, and v6), robust accessibility features, and strict enforcement of unique node values to optimize performance for internal state management.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'length') or visually unstyled/broken component display.
```
cause The essential CSS stylesheet for `react-checkbox-tree` has not been imported or is not correctly loaded into the application.

fix Add `import 'react-checkbox-tree/lib/react-checkbox-tree.css';` to your application's entry file (e.g., `index.js`/`index.tsx`) or the React component where `CheckboxTree` is being rendered.
```
Error: Node object property 'value' must be unique. (or similar runtime error related to duplicate keys).
```
cause Two or more node objects within the `nodes` prop have identical `value` properties, violating the component's unique value requirement.

fix Inspect your `nodes` array for any duplicate `value` strings. Each node's `value` must be unique across the entire tree structure.
```
TypeError: CheckboxTree is not a function or Element type is invalid: expected a string (for built-in components) or a class/function (for composite components).
```
cause The `CheckboxTree` component is being imported incorrectly, either using CommonJS `require()` in an ES module context or misinterpreting its default export.

fix Ensure you are using `import CheckboxTree from 'react-checkbox-tree';`. If explicitly using CommonJS, `const CheckboxTree = require('react-checkbox-tree').default;` may be necessary.
```
Clicking checkboxes or expand/collapse icons has no effect; the tree state appears frozen.
```
cause The `CheckboxTree` is a controlled component, but the `checked` or `expanded` props are not being updated by their respective `onCheck` or `onExpand` event handlers, preventing state changes from being reflected.

fix Verify that your `onCheck` and `onExpand` callback functions are correctly updating the state variables (e.g., using `setChecked` and `setExpanded` from `useState`) that are then passed back into the `checked` and `expanded` props.

Warnings

breaking Version 2.0.0 introduced significant breaking changes related to accessibility. The clickable label's ARIA `role` was changed from `link` to `button`, and the pseudo-checkbox is now hidden from the accessibility tree to improve screen reader compatibility.
Fix: Review any custom styling or accessibility integrations that might rely on the previous ARIA roles or structure. If using the `lang` prop, update your configuration as the `toggle` key has been replaced by `collapseNode`.
breaking In version 2.0.0 and later, the `id` property on the `CheckboxTree` component will no longer automatically generate a random UUID if left empty. If you rely on a unique `id` for DOM manipulation or testing, it must now be explicitly provided.
Fix: Ensure that a unique `id` string is explicitly passed to the `CheckboxTree` component's `id` prop if you require a specific or stable DOM ID. If no `id` is provided, the component will not generate one.
gotcha The component relies on Font Awesome CSS (v4, v5, or v6) to be loaded in your application for its default icons to render correctly. Without it, you will observe missing or broken icons.
Fix: Include Font Awesome CSS in your project (e.g., via CDN, npm package, or build system). Alternatively, provide custom icon components via the `icons` prop to override the defaults entirely.
gotcha react-checkbox-tree is a controlled component. Its `checked` and `expanded` props must be managed externally by your React component's state. Failure to update these states via the `onCheck` and `onExpand` handlers will result in a non-interactive tree.
Fix: Always pass state variables (e.g., from `useState`) to the `checked` and `expanded` props, and ensure that their corresponding `onCheck` and `onExpand` event handlers are correctly updating those state variables.
gotcha All node objects within the `nodes` array passed to the component must have a unique `value` property. Duplicate values across any level of the tree will lead to unexpected behavior and can cause errors, as the component relies on `value` for internal state serialization.
Fix: Carefully review your `nodes` data structure and ensure that every node object, regardless of its position in the hierarchy, possesses a unique string `value`.

Install

npm install react-checkbox-tree npm
yarn add react-checkbox-tree yarn
pnpm add react-checkbox-tree pnpm

Imports

CheckboxTree
wrong:
```
const CheckboxTree = require('react-checkbox-tree');
```
correct:
```
import CheckboxTree from 'react-checkbox-tree';
```
The main component is a default export. Use ES module import syntax for modern React projects. The `require` syntax might work if your build system handles interop, but it's not the idiomatic way.
CSS Styles
```
import 'react-checkbox-tree/lib/react-checkbox-tree.css';
```
The component's essential styling is provided via a CSS file. This import should typically be placed in your application's root or the component using CheckboxTree.
Node
```
import type { Node } from 'react-checkbox-tree';
```
Type definition for the `nodes` array structure. Highly recommended for TypeScript projects to ensure correct node object shape.
OnCheckChangeEventHandler
```
import type { OnCheckChangeEventHandler } from 'react-checkbox-tree';
```
Type definition for the `onCheck` and `onExpand` event handler functions, providing type safety for their arguments in TypeScript.

Quickstart

This example demonstrates how to integrate `react-checkbox-tree` into a React application, managing its controlled `checked` and `expanded` states using React hooks. It also shows the necessary CSS import and basic node definition.

import React, { useState } from 'react';
import CheckboxTree from 'react-checkbox-tree';
import 'react-checkbox-tree/lib/react-checkbox-tree.css';

const nodes = [
  {
    value: 'grand-parent',
    label: 'Grand Parent',
    children: [
      { value: 'parent-1', label: 'Parent 1',
        children: [
          { value: 'child-1a', label: 'Child 1a' },
          { value: 'child-1b', label: 'Child 1b' },
        ],
      },
      { value: 'parent-2', label: 'Parent 2' },
    ],
  },
  { value: 'single-node', label: 'A Standalone Node' }
];

function MyCheckboxTreeWidget() {
  // State for checked nodes, initialized as an empty array
  const [checked, setChecked] = useState<string[]>([]);
  // State for expanded nodes, initialized as an empty array
  const [expanded, setExpanded] = useState<string[]>([]);

  return (
    <div style={{ padding: '20px', maxWidth: '400px', border: '1px solid #eee', borderRadius: '5px' }}>
      <h2>Hierarchical Selection</h2>
      <p>Selected items: <strong>{checked.length > 0 ? checked.join(', ') : 'None'}</strong></p>
      <CheckboxTree
        nodes={nodes}
        checked={checked}
        expanded={expanded}
        onCheck={(checkedList) => setChecked(checkedList)}
        onExpand={(expandedList) => setExpanded(expandedList)}
        showExpandAll={true}
        showNodeIcon={false}
      />
    </div>
  );
}

export default MyCheckboxTreeWidget;

// To use this in your App.tsx or App.jsx:
// import MyCheckboxTreeWidget from './MyCheckboxTreeWidget';
// function App() {
//   return <MyCheckboxTreeWidget />;
// }

view raw JSON →