A simple and elegant checkbox tree for React.
npm install react-checkbox-tree-duplicate-value
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` |