react-checkbox-tree


> A simple and elegant checkbox tree for React.

!Demo

Usage

$3

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.

$3

For your convenience, the library's styles can be consumed utilizing one of the following files:

* node_modules/react-checkbox-tree/lib/react-checkbox-tree.css
* node_modules/react-checkbox-tree/src/less/react-checkbox-tree.less
* 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';
`

$3

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';

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 (
nodes={nodes}
checked={checked}
expanded={expanded}
onCheck={(checked) => 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
...
iconsClass="fa4"
/>
`

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
...
icons={{
check: ,
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'

...

...
icons={{
check: ,
uncheck: ,
halfCheck: ,
expandClose: ,
expandOpen: ,
expandAll: ,
collapseAll: ,
parentClose: ,
parentOpen: ,
leaf:
}}
/>
`

$3

In addition to the CheckboxTree component, additional utility functions are available to set the initial state of the 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.

$3

| Property | Type | Description | Default |
| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | ----------- |
| nodes | array | Required. Specifies the tree nodes and their children. | |
| 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' and 'fa5' are supported. | 'fa5' |
| id | string | A string to be used for the HTML ID of the rendered tree and its nodes. | null |
| lang | object | An object containing the language mappings for the various text elements. | { ... } |
| 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 |
| 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. | () => {} |
| 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
[react-fontawesome]: https://github.com/FortAwesome/react-fontawesome