@r365/react-checkbox-tree


> A simple and elegant checkbox tree for React.

!Demo

Usage

$3

Install the library using your favorite dependency manager:

``
yarn add @r365/react-checkbox-tree
`

Using npm:

`
npm install @r365/react-checkbox-tree --save
`

> Note – This library makes use of 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/@r365/react-checkbox-tree/lib/react-checkbox-tree.css
* node_modules/@r365/react-checkbox-tree/src/less/react-checkbox-tree.less
* node_modules/@r365/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 '@r365/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, it is stateless. You must update its checked and expanded properties whenever a change occurs.

` jsx
import React from 'react';
import CheckboxTree from '@r365/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, @r365/react-checkbox-tree uses Font Awesome for the various icons that appear in the tree. To change the defaults, 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

| Property | Type | Description | Default |
| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | ----------- |
| nodes | array | Required. Specifies the tree nodes and their children. | |
| checked | array | An array of checked node values. | [] |
| 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 |
| icons | object | An object containing the mappings for the various icons and their components. See Changing the Default Icons. | { ... } |
| id | string | A string to be used for the HTML ID of the rendered tree and its nodes. | null |
| expanded | array | An array of expanded node values. | [] |
| 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` |