React Hook Checkbox

An easy to use, all-in-one, minimal setup, React Hook for checkboxes.


$3

- TypeScript Support complete with JSDocs.
- Small Size (<2kb minifed) and Zero Dependencies.
- Select All, Indeterminate, Custom Properties, and Checkbox Nesting.
- Built-in API for State Manipulation.
- Minimal Configuration and Integration necassary.

Demo

Table of Contents

Quickstart |
API |
Usage |
FAQ

$3

npm install react-hook-checkbox

$3

``jsx
import * as React from "react";

import { useCheckbox } from "react-hook-checkbox";

const config = {
name: "Shopping List",
options: [{
name: "Eggs",
}, {
name: "Milk",
}, {
name: "Cheese",
}]
};

const MyPage = () => {

const [myCheckbox] = useCheckbox(config);

return (
<>
{myCheckbox.options.map((option, index) => {
return (

type="checkbox"
checked={option.isSelected}
onChange={() => option.select()}
/>
{option.name}

);
})}

);
};

export default MyPage;
`

API

$3

Checkboxes are built with a user-provided configuration object hereinafter referred to as checkboxConfig. The checkboxConfig accepts the following parameters:

- name - the name of the checkbox. Defaults to "".
- options - any child checkboxes. Defaults to [].
- properties - properties provided to the checkbox. Defaults to undefined,
- isSelected - true/false if the checkbox is selected. Defaults to false.

\* all of these paramers are optional

$3

Creates the checkboxes from the provided checkboxConfig. Returns a React hook.

All checkboxes (myList and its options) share the same properties/functions as described below:

$3

- .name - name of the checkbox
- .options - arrary of any child checkboxes. [] if there are none.
- .properties - properties provided to the checkbox.
- .isSelected - true/false if checkbox is selected.
- .ref - refrence to the parent checkbox. undefined if there's no parent.

Note: Remember to follow React's rule's of Hooks when working with .properties.

$3

$3

Resets and creates a new checkbox on from the provided configuration.
Accepts a checkboxConfig.

$3

Resets the .options to a new set of options from the provided configuration.
Accepts a checkboxConfig[].

$3

Adds a child checkbox to .options from the provided configuration.
Accepts a checkboxConfig.

$3

Sets the .isSelected of the checkbox.
Accepts a boolean.

$3

Sets the .properties of the checkbox.
Accepts an any.

$3

Sets the .name of the checkbox.
Accepts a string.

$3

Returns an array of all child checkboxes in which .isSelected is true.

$3

Returns true/false if the checkbox is indeterminate.

$3

Returns true/false if .isSelected of all child checkboxes is true.

$3

Returns true/false if .isSelected of any child checkbox is true.

$3

Removes a checkbox from the parent checkbox's .options.

$3

Selects a single checkbox, inverting the current .isSelected.

Usage

Setting the initial state:

`jsx
const config = {
name: 'List',
isSelected: false,
properties: { myProperties: "hello world!"},
options: [{
name: 'Option 1',
isSelected: true,
properties: { myProperties: "fizz!"}
}, {
name: 'Option 2',
isSelected: false,
properties: { myProperties: "buzz!"}
}, {
name: 'Option 3',
isSelected: true,
properties: { myProperties: "fizzbuzz!"}
}]
};

const MyPage = () => {

const [myCheckbox] = useCheckbox(config);

return (
<>

Will say "FizzBuzz":

{myCheckbox.options[2].properties.myProperties}

);
};
`
Utilizing default values:
`jsx
const MyPage = () => {

// since all paramters are options {} is valid use of useCheckbox()
const [myCheckbox] = useCheckbox({});

return (
<>

name is "" by default

{myCheckbox.name}

isSelected is false by default

{myCheckbox.isSelected ? "true" : "false"}

);
};
`
Setting name, options, properties and adding/removing options:
`jsx
const MyPage = () => {

const [myCheckbox] = useCheckbox(config);

const option = {
name: "new option"
}

const options = [{
name: "new option 1"
}, {
name: "new option 2"
}]

const newProperties = { myProperties: "new property" };

// display new list in console on rerender
console.log(myCheckbox);

return (
<>
myCheckbox.setName("new name")}>Set Name
myCheckbox.setProperties(newProperties)}>Set Properties
myCheckbox.addOption(option)}>Add Option
myCheckbox.setOptions(options)}>Set Option
myCheckbox.options[0].removeOption()}>Remove First Option

);
};
`
Display a single set of checkboxes:
`jsx
const MyPage = () => {

const [myCheckbox] = useCheckbox(config);

return (
<>
{myCheckbox.options.map((option, index) => {
return (

type="checkbox"
checked={option.isSelected}
onChange={() => option.select()}
/>
{option.name}

);
})}

);
};
`
Display all checkboxes recursively:

`jsx
const MyPage = () => {

const [myCheckbox] = useCheckbox(config);

const displayCheckboxex = (checkbox) => {
return (

type="checkbox"
checked={checkbox.isSelected}
onChange={() => checkbox.select()}
ref={input => {
if (input) {
input.indeterminate = checkbox.isIndeterminate();
}
}}
/>
{checkbox.name}
{checkbox.options.map((option, index) => {
return (

{myCheckbox.options.length ?
displayCheckboxex(option)
:
<>
}

);
})}

)
}

return (
<>
{displayCheckboxex(myCheckbox)}

);
};
`
Usage with TypeScript:
`jsx
type MyType = string;

const config: CheckboxConfig = {
properties: "fizzbuzz"
};

const MyPage = () => {

const [myCheckbox] = useCheckbox(config);

return (
<>
{myCheckbox.properties}

);
};

``

FAQ

$3

Please raise an issue on the Github repository.

$3

Yes! If you'd like to contribute to the project, please raise a pull request.

$3

Feel free to send me an email: nfrederick023@gmail.com