react-checkbox-tree

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 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:

import 'react-checkbox-tree/lib/react-checkbox-tree.css';

Render Component

Below is a minimal example using state hooks. Note that CheckboxTree is a controlled component, so you must update its checked and expanded properties whenever a change occurs.

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 (
    <CheckboxTree
      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":

<CheckboxTree
    ...
    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:

<CheckboxTree
    ...
    icons={{
        check: <span className="rct-icon rct-icon-check" />,
        uncheck: <span className="rct-icon rct-icon-uncheck" />,
        halfCheck: <span className="rct-icon rct-icon-half-check" />,
        expandClose: <span className="rct-icon rct-icon-expand-close" />,
        expandOpen: <span className="rct-icon rct-icon-expand-open" />,
        expandAll: <span className="rct-icon rct-icon-expand-all" />,
        collapseAll: <span className="rct-icon rct-icon-collapse-all" />,
        parentClose: <span className="rct-icon rct-icon-parent-close" />,
        parentOpen: <span className="rct-icon rct-icon-parent-open" />,
        leaf: <span className="rct-icon rct-icon-leaf" />,
    }}
/>

If you are using the react-fontawesome library, you can also directly substitute those icons:

import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'

...

<CheckboxTree
    ...
    icons={{
        check: <FontAwesomeIcon className="rct-icon rct-icon-check" icon="check-square" />,
        uncheck: <FontAwesomeIcon className="rct-icon rct-icon-uncheck" icon={['fas', 'square']} />,
        halfCheck: <FontAwesomeIcon className="rct-icon rct-icon-half-check" icon="check-square" />,
        expandClose: <FontAwesomeIcon className="rct-icon rct-icon-expand-close" icon="chevron-right" />,
        expandOpen: <FontAwesomeIcon className="rct-icon rct-icon-expand-open" icon="chevron-down" />,
        expandAll: <FontAwesomeIcon className="rct-icon rct-icon-expand-all" icon="plus-square" />,
        collapseAll: <FontAwesomeIcon className="rct-icon rct-icon-collapse-all" icon="minus-square" />,
        parentClose: <FontAwesomeIcon className="rct-icon rct-icon-parent-close" icon="folder" />,
        parentOpen: <FontAwesomeIcon className="rct-icon rct-icon-parent-open" icon="folder-open" />,
        leaf: <FontAwesomeIcon className="rct-icon rct-icon-leaf-close" icon="file" />
    }}
/>

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

onCheck and onExpand

Node Properties

Individual nodes within the nodes property can have the following structure: