Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including react-checkbox-tree with all npm packages installed. Try it out:

require("react/package.json"); // react is a peer dependency. var reactCheckboxTree = require("react-checkbox-tree")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

react-checkbox-tree v1.6.0

A simple and elegant checkbox tree for React.

react-checkbox-tree

npm Build Status Dependency Status devDependency Status Greenkeeper badge GitHub license

A simple and elegant checkbox tree for React.

Demo

Usage

Installation

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.

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

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.

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

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

<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" />
    }}
/>

Properties

PropertyTypeDescriptionDefault
nodesarrayRequired. Specifies the tree nodes and their children.
checkModelboolSpecifies which checked nodes should be stored in the checked array. Accepts 'leaf' or 'all'.'leaf'
checkedarrayAn array of checked node values.[]
disabledboolIf true, the component will be disabled and nodes cannot be checked.false
expandDisabledboolIf true, the ability to expand nodes will be disabled.false
expandOnClickboolIf true, nodes will be expanded by clicking on labels. Requires a non-empty onClick function.false
expandedarrayAn array of expanded node values.[]
iconsobjectAn object containing the mappings for the various icons and their components. See Changing the Default Icons.{ ... }
iconsClassstringA string that specifies which icons class to utilize. Currently, 'fa4' and 'fa5' are supported.'fa4'
idstringA string to be used for the HTML ID of the rendered tree and its nodes.null
langobjectAn object containing the language mappings for the various text elements.{ ... }
namestringOptional name for the hidden <input> element.undefined
nameAsArrayboolIf true, the hidden <input> will encode its values as an array rather than a joined string.false
nativeCheckboxesboolIf true, native browser checkboxes will be used instead of pseudo-checkbox icons.false
noCascadeboolIf true, toggling a parent node will not cascade its check state to its children.false
onlyLeafCheckboxesboolIf true, checkboxes will only be shown for leaf nodes.false
optimisticToggleboolIf true, toggling a partially-checked node will select all children. If false, it will deselect.true
showExpandAllboolIf true, buttons for expanding and collapsing all parent nodes will appear in the tree.false
showNodeIconboolIf true, each node will show a parent or leaf icon.true
showNodeTitleboolIf true, the label of each node will become the title of the resulting DOM node. Overridden by node.title.false
onCheckfunctiononCheck handler: function(checked, targetNode) {}() => {}
onClickfunctiononClick handler: function(targetNode) {}. If set, onClick will be called when a node's label has been clicked.() => {}
onExpandfunctiononExpand handler: function(expanded, targetNode) {}() => {}

onCheck and onExpand

Node Properties

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

PropertyTypeDescriptionDefault
labelmixedRequired. The node's label.
valuemixedRequired. The node's value.
childrenarrayAn array of child nodes.null
classNamestringA className to add to the node.null
disabledboolWhether the node should be disabled.false
iconmixedA custom icon for the node.null
showCheckboxboolWhether the node should show a checkbox.true
titlestringA custom title attribute for the node.null
RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free