{"id":11660,"library":"react-checkbox-tree","title":"React Checkbox Tree","description":"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.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/jakezatecky/react-checkbox-tree","tags":["javascript","react","checkbox","tree","typescript"],"install":[{"cmd":"npm install react-checkbox-tree","lang":"bash","label":"npm"},{"cmd":"yarn add react-checkbox-tree","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-checkbox-tree","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for all React applications.","package":"react","optional":false},{"reason":"By 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.","package":"font-awesome","optional":true}],"imports":[{"note":"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.","wrong":"const CheckboxTree = require('react-checkbox-tree');","symbol":"CheckboxTree","correct":"import CheckboxTree from 'react-checkbox-tree';"},{"note":"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.","wrong":null,"symbol":"CSS Styles","correct":"import 'react-checkbox-tree/lib/react-checkbox-tree.css';"},{"note":"Type definition for the `nodes` array structure. Highly recommended for TypeScript projects to ensure correct node object shape.","wrong":null,"symbol":"Node","correct":"import type { Node } from 'react-checkbox-tree';"},{"note":"Type definition for the `onCheck` and `onExpand` event handler functions, providing type safety for their arguments in TypeScript.","wrong":null,"symbol":"OnCheckChangeEventHandler","correct":"import type { OnCheckChangeEventHandler } from 'react-checkbox-tree';"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport CheckboxTree from 'react-checkbox-tree';\nimport 'react-checkbox-tree/lib/react-checkbox-tree.css';\n\nconst nodes = [\n  {\n    value: 'grand-parent',\n    label: 'Grand Parent',\n    children: [\n      { value: 'parent-1', label: 'Parent 1',\n        children: [\n          { value: 'child-1a', label: 'Child 1a' },\n          { value: 'child-1b', label: 'Child 1b' },\n        ],\n      },\n      { value: 'parent-2', label: 'Parent 2' },\n    ],\n  },\n  { value: 'single-node', label: 'A Standalone Node' }\n];\n\nfunction MyCheckboxTreeWidget() {\n  // State for checked nodes, initialized as an empty array\n  const [checked, setChecked] = useState<string[]>([]);\n  // State for expanded nodes, initialized as an empty array\n  const [expanded, setExpanded] = useState<string[]>([]);\n\n  return (\n    <div style={{ padding: '20px', maxWidth: '400px', border: '1px solid #eee', borderRadius: '5px' }}>\n      <h2>Hierarchical Selection</h2>\n      <p>Selected items: <strong>{checked.length > 0 ? checked.join(', ') : 'None'}</strong></p>\n      <CheckboxTree\n        nodes={nodes}\n        checked={checked}\n        expanded={expanded}\n        onCheck={(checkedList) => setChecked(checkedList)}\n        onExpand={(expandedList) => setExpanded(expandedList)}\n        showExpandAll={true}\n        showNodeIcon={false}\n      />\n    </div>\n  );\n}\n\nexport default MyCheckboxTreeWidget;\n\n// To use this in your App.tsx or App.jsx:\n// import MyCheckboxTreeWidget from './MyCheckboxTreeWidget';\n// function App() {\n//   return <MyCheckboxTreeWidget />;\n// }","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.7.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The essential CSS stylesheet for `react-checkbox-tree` has not been imported or is not correctly loaded into the application.","error":"TypeError: Cannot read properties of undefined (reading 'length') or visually unstyled/broken component display."},{"fix":"Inspect your `nodes` array for any duplicate `value` strings. Each node's `value` must be unique across the entire tree structure.","cause":"Two or more node objects within the `nodes` prop have identical `value` properties, violating the component's unique value requirement.","error":"Error: Node object property 'value' must be unique. (or similar runtime error related to duplicate keys)."},{"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.","cause":"The `CheckboxTree` component is being imported incorrectly, either using CommonJS `require()` in an ES module context or misinterpreting its default export.","error":"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)."},{"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.","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.","error":"Clicking checkboxes or expand/collapse icons has no effect; the tree state appears frozen."}],"ecosystem":"npm"}