# react-checkbox-tree > A simple and elegant checkbox tree for React. Latest version **2.1.1** (published 2026-09-27) · MIT license · 0 weekly downloads ## Install ```sh npm install react-checkbox-tree pnpm add react-checkbox-tree yarn add react-checkbox-tree bun add react-checkbox-tree ``` ## Health **Score 70/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 2.1.1 | | Published | 2026-09-27 | | First published | 2016-02-04 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 4 | | Unpacked size | 4.3 MB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | Jake Zatecky | | Maintainers | jzatecky | | Keywords | react, checkbox, tree | ## Links - npm: https://www.npmjs.com/package/react-checkbox-tree - Repository: https://github.com/jakezatecky/react-checkbox-tree - Homepage: https://jakezatecky.github.io/react-checkbox-tree - Issues: https://github.com/jakezatecky/react-checkbox-tree/issues - npm.io page: https://npm.io/package/react-checkbox-tree ## Dependencies (4) - [classnames](https://npm.io/package/classnames.md) ^2.2.5 - [prop-types](https://npm.io/package/prop-types.md) ^15.5.8 - [fast-equals](https://npm.io/package/fast-equals.md) ^6.0.0 - [lodash.memoize](https://npm.io/package/lodash.memoize.md) ^4.1.2 ## Alternatives - [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads - [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads - [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads - [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads - [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads ## Recent versions - 2.1.1 (latest) — 2026-09-27 - 1.6.0-alpha.2 (next) — 2019-04-24 - 2.1.0 — 2026-09-27 - 2.0.2 — 2026-05-28 - 2.0.1 — 2026-04-18 - 2.0.0 — 2026-04-09 - 1.8.0 — 2022-09-06 - 1.7.3 — 2022-05-23 - 1.7.2 — 2021-08-09 - 1.7.1 — 2021-06-08 - 1.7.0 — 2021-06-08 - 1.6.0 — 2019-12-11 - 1.5.1 — 2019-01-28 - 1.6.0-alpha.1 — 2019-01-28 - 1.6.0-alpha.0 — 2019-01-28 - … 39 more at https://npm.io/package/react-checkbox-tree/versions ## README # react-checkbox-tree [![npm](https://img.shields.io/npm/v/react-checkbox-tree.svg?style=flat-square)](https://www.npmjs.com/package/react-checkbox-tree) [![Build Status](https://img.shields.io/github/actions/workflow/status/jakezatecky/react-checkbox-tree/main.yml?branch=master&style=flat-square)](https://github.com/jakezatecky/react-checkbox-tree/actions/workflows/main.yml) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://raw.githubusercontent.com/jakezatecky/react-checkbox-tree/master/LICENSE.txt) > A simple and elegant checkbox tree for React. ![Demo](demo.gif) ## Usage ### Installation Install the library using your favorite dependency manager: ``` yarn add react-checkbox-tree ``` Using npm: ``` npm install react-checkbox-tree --save ``` > **Note** – By default, this library makes use of [Font Awesome][font-awesome] styles and expects them to be loaded in the browser. ### Include CSS The library's styles are available through one of the following files: * `node_modules/react-checkbox-tree/lib/react-checkbox-tree.css` * `node_modules/react-checkbox-tree/src/scss/react-checkbox-tree.scss` Either include one of these files in your stylesheets or utilize a CSS loader: ``` javascript import 'react-checkbox-tree/lib/react-checkbox-tree.css'; ``` ### Render Component Below is a minimal example using [state hooks][docs-state-hooks]. Note that `CheckboxTree` is a [controlled][docs-controlled] component, so you must update its `checked` and `expanded` properties whenever a change occurs. ``` jsx import React, { useState } from 'react'; import CheckboxTree from 'react-checkbox-tree'; import 'react-checkbox-tree/lib/react-checkbox-tree.css'; const nodes = [{ value: 'mars', label: 'Mars', children: [ { value: 'phobos', label: 'Phobos' }, { value: 'deimos', label: 'Deimos' }, ], }]; function Widget() { const [checked, setChecked] = useState([]); const [expanded, setExpanded] = useState([]); return ( setChecked(checked)} onExpand={(expanded) => setExpanded(expanded)} /> ); } ``` > **Note** – All node objects **must** have a unique `value`. This component serializes the values into the `checked` and `expanded` array for performance optimizations. #### Changing the Default Icons By default, **react-checkbox-tree** uses Font Awesome 5/6 for the various icons that appear in the tree. To utilize Font Awesome 4 icons, simply pass in `iconsClass="fa4"`: ``` jsx ``` To change the rendered icons entirely, simply pass in the `icons` property and override the defaults. Note that you can override as many or as little icons as you like: ``` jsx , uncheck: , halfCheck: , expandClose: , expandOpen: , expandAll: , collapseAll: , parentClose: , parentOpen: , leaf: , }} /> ``` If you are using the [`react-fontawesome`][react-fontawesome] library, you can also directly substitute those icons: ``` jsx import { FontAwesomeIcon } from '@fortawesome/react-fontawesome' ... , uncheck: , halfCheck: , expandClose: , expandOpen: , expandAll: , collapseAll: , parentClose: , parentOpen: , leaf: }} /> ``` ### Utility Functions In addition to the `CheckboxTree` component, additional utility functions are available to set the initial state of the tree. #### `checkAllNodes(nodes, options)` Creates a list of node keys that checks every enabled node in the tree. Pass the result to the `checked` property to implement "check all" functionality. Disabled nodes, as well as the descendants of disabled parents when cascading, are left unchecked. Arguments: * `nodes` (`Array`): The same array of nodes passed into the main `CheckboxTree` component * `options` (`Object`): Optional. Should match the properties passed into the `CheckboxTree` component. * `checkModel` (`string`): Either `'leaf'` or `'all'`. Defaults to `'leaf'`. * `noCascade` (`bool`): Defaults to `false`. Returns: * `Array`: A list of node keys. ``` jsx import CheckboxTree, { checkAllNodes } from 'react-checkbox-tree'; ... ``` #### `expandNodesToLevel(nodes, targetLevel)` Creates a list of all parent node keys until `targetLevel`. Arguments: * `nodes` (`Array`): The same array of nodes passed into the main `CheckboxTree` component * `targetLevel` (`number`): The maximum expansion depth. Use `Infinity` for maximum depth. Returns: * `Array`: A list of node keys. ### Properties | Property | Type | Description | Default | | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | ---------------- | | `nodes` | array | **Required**. Specifies the tree nodes and their children. | | | `checkKeys` | array | A list of [keyboard keys][mdn-key] that will trigger a toggle of the check status of a node. | `[' ', 'Enter']` | | `checkModel` | string | Specifies which checked nodes should be stored in the `checked` array. Accepts `'leaf'` or `'all'`. | `'leaf'` | | `checked` | array | An array of checked node values. | `[]` | | `direction` | string | A string that specify whether the direction of the component is left-to-right (`'ltr'`) or right-to-left (`'rtl'`). | `'ltr'` | | `disabled` | bool | If true, the component will be disabled and nodes cannot be checked. | `false` | | `expandDisabled` | bool | If true, the ability to expand nodes will be disabled. | `false` | | `expandOnClick` | bool | If true, nodes will be expanded by clicking on labels. Requires a non-empty `onClick` function. | `false` | | `expanded` | array | An array of expanded node values. | `[]` | | `icons` | object | An object containing the mappings for the various icons and their components. See **Changing the Default Icons**. | `{ ... }` | | `iconsClass` | string | A string that specifies which icons class to utilize. Currently, `'fa4'`, `'fa5'`, and `'fa6'` are supported. | `'fa5'` | | `id` | string | A string to be used for the HTML ID of the rendered tree and its nodes. | `null` | | `lang` | object | A key-value pairing of localized text. See [`src/js/lang/default.js`][lang-file] for a list of keys. | `{ ... }` | | `listTag` | string | Either `ol` or `ul`. This determines the underlying HTML tag (`
    ` vs. `
      `). | `'ol'` | | `name` | string | Optional name for the hidden `` element. | `undefined` | | `nameAsArray` | bool | If true, the hidden `` will encode its values as an array rather than a joined string. | `false` | | `nativeCheckboxes` | bool | If true, native browser checkboxes will be used instead of pseudo-checkbox icons. | `false` | | `noCascade` | bool | If true, toggling a parent node will **not** cascade its check state to its children. | `false` | | `onlyLeafCheckboxes` | bool | If true, checkboxes will only be shown for leaf nodes. | `false` | | `optimisticToggle` | bool | If true, toggling a partially-checked node will select all children. If false, it will deselect. | `true` | | `preserveUnknownValues` | bool | If true, `onCheck` and `onExpand` will keep values that are not in `nodes`. Useful when filtering nodes. | `false` | | `showExpandAll` | bool | If true, buttons for expanding and collapsing all parent nodes will appear in the tree. | `false` | | `showNodeIcon` | bool | If true, each node will show a parent or leaf icon. | `true` | | `showNodeTitle` | bool | If true, the `label` of each node will become the `title` of the resulting DOM node. Overridden by `node.title`. | `false` | | `onCheck` | function | onCheck handler: `function(checked, targetNode) {}` | `() => {}` | | `onClick` | function | onClick handler: `function(targetNode) {}`. If set, `onClick` will be called when a node's label has been clicked. | `null` | | `onContextMenu` | function | onContextMenu handler: `function(event, targetNode) {}`. Triggers when right-clicking a node element. | `null` | | `onExpand` | function | onExpand handler: `function(expanded, targetNode) {}` | `() => {}` | #### `onCheck` and `onExpand` #### Node Properties Individual nodes within the `nodes` property can have the following structure: | Property | Type | Description | Default | | -------------- | ------ | ---------------------------------------- | ------- | | `label` | mixed | **Required**. The node's label. | | | `value` | mixed | **Required**. The node's value. | | | `children` | array | An array of child nodes. | `null` | | `className` | string | A className to add to the node. | `null` | | `disabled` | bool | Whether the node should be disabled. | `false` | | `icon` | mixed | A custom icon for the node. | `null` | | `showCheckbox` | bool | Whether the node should show a checkbox. | `true` | | `title` | string | A custom `title` attribute for the node. | `null` | [docs-controlled]: https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components [docs-state-hooks]: https://react.dev/reference/react/useState [font-awesome]: https://fontawesome.com [lang-file]: https://github.com/jakezatecky/react-checkbox-tree/blob/master/src/js/lang/default.js [mdn-key]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key [react-fontawesome]: https://github.com/FortAwesome/react-fontawesome --- _Source: https://npm.io/package/react-checkbox-tree · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._