Registry / web-framework / react-checkbox-tree

react-checkbox-tree

library2.0.1jsnpmunverified

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.

web-framework

npm install react-checkbox-tree

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-CHECKBOX-TRE

react-checkbox-tree

web-frameworkjavascriptv2.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CheckboxTree

✓ import CheckboxTree from 'react-checkbox-tree';

✗ const CheckboxTree = require('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.

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 />; // }

Debug

Known issues

breakingVersion 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`.

affects: >=2.0.0

breakingIn 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.

affects: >=2.0.0

gotchaThe 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.

affects: >=1.0.0

gotchareact-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.

affects: >=1.0.0

gotchaAll 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`.

affects: >=1.7.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'length') or visually unstyled/broken component display.

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).

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).

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.

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.

Upgrade

Version history

2.0.1latest on npm

Audit

Dependencies

reactrequiredPeer dependency for all React applications.

font-awesomeoptionalBy default, the component uses Font Awesome icons and expects its CSS to be loaded. This is not a direct npm dependency, but a styling prerequisite.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/jakezatecky/react-checkbox-tree ↗

packagehttps://www.npmjs.com/package/react-checkbox-tree ↗

homepagehttps://jakezatecky.github.io/react-checkbox-tree ↗