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 – This library makes use of Font Awesome styles and expects them to be loaded in the browser.

> Note – Although React 18 should work, our unit tests run against React 17 due to incompatibility with the unit testing tool (Enzyme).

$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

A quick usage example is included below. Note that the react-checkbox-tree component is controlled. In other words, you must update its checked and expanded properties whenever a change occurs.

`jsx
import React from "react";
import CheckboxTree from "react-checkbox-tree";

const nodes = [
{
value: "mars",
label: "Mars",
children: [
{ value: "phobos", label: "Phobos" },
{ value: "deimos", label: "Deimos" },
],
},
];

class Widget extends React.Component {
state = {
checked: [],
expanded: [],
};

render() {
return (
nodes={nodes}
checked={this.state.checked}
expanded={this.state.expanded}
onCheck={(checked) => this.setState({ checked })}
onExpand={(expanded) => this.setState({ expanded })}
/>
);
}
}
`

All node objects must have a unique value. This value is serialized into the checked and expanded arrays and is also used for performance optimizations.

#### Changing the Default Icons

By default, react-checkbox-tree uses Font Awesome 4 for the various icons that appear in the tree. To utilize Font Awesome 5 icons, simply pass in iconsClass="fa5":

`jsx
...
iconsClass="fa5"
/>
`

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 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. | 'fa4' |
| 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` |