Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jakezatecky/react-checkbox-tree
A simple and elegant checkbox tree for React.
https://github.com/jakezatecky/react-checkbox-tree
checkbox-treeview react tree treeview
Last synced: 11 days ago
JSON representation
A simple and elegant checkbox tree for React.
- Host: GitHub
- URL: https://github.com/jakezatecky/react-checkbox-tree
- Owner: jakezatecky
- License: mit
- Created: 2016-02-04T04:53:33.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2024-03-08T10:36:27.000Z (8 months ago)
- Last Synced: 2024-10-20T04:15:22.666Z (23 days ago)
- Topics: checkbox-treeview, react, tree, treeview
- Language: JavaScript
- Homepage: https://jakezatecky.github.io/react-checkbox-tree/
- Size: 2.57 MB
- Stars: 707
- Watchers: 15
- Forks: 211
- Open Issues: 99
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# react-checkbox-tree
[](https://www.npmjs.com/package/react-checkbox-tree)
[](https://github.com/jakezatecky/react-checkbox-tree/actions/workflows/main.yml)
[](https://raw.githubusercontent.com/jakezatecky/react-checkbox-tree/master/LICENSE.txt)
> A simple and elegant checkbox tree for React.
## 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
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';
```
### 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';
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.
#### `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. | |
| `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