react-tri-state-checkbox

A mixed-state checkbox for React based on the WAI-ARIA Authoring Practices's tri-state checkbox. For more details see this specification.

---

Installation

$ npm i react-tri-state-checkbox

---

Usage

The following example demonstrates how the react-tri-state-checkbox components work together in an accessible example:

import React from 'react'
import {
  Checkbox,
  TriStateCheckbox,
  TriStateContext,
} from 'react-tri-state-checkbox'
import 'react-tri-state-checkbox/dist/styles.css'
 
const CondimentsSelect = () => (
  <TriStateContext controls={['cond1', 'cond2', 'cond3']}>
    <fieldset role="group" aria-labelledby="all-condiments-input">
      <legend>Sandwich Condiments</legend>
 
      <TriStateCheckbox id="all-condiments-input">
        All condiments
      </TriStateCheckbox>
 
      <label>
        {/* checked by default */}
        <Checkbox id="cond1" checked />
        Lettuce
      </label>
 
      <label>
        <Checkbox id="cond2" />
        Tomato
      </label>
 
      <label>
        <Checkbox id="cond3" />
        Mustard
      </label>
    </fieldset>
  </TriStateContext>
)

Note: For details about accessibility considerations please see this document by the W3C detailing proper implementation.

<TriStateContext />

A context wrapper that handles checkbox state changes. Must wrap <TriStateCheckbox /> and <Checkbox />.

Props

Name	Type	Required	Description
controls	Array	✅	An array of controlled checkbox ids.

<TriStateCheckbox />

The mixed-state checkbox component.

Props

Name	Type	Required	Description
render	Function	❌	A function used to render the mixed-state checkbox. The current state is passed as the prop aria-checked, which can be either true, false or 'mixed'.

Please note that if you are not rendering your own checkbox for this component, you probably want to import the default styles for the mixed-state checkbox by importing the following stylesheet:

import 'react-tri-state-checkbox/styles/checkbox.css'

<Checkbox />

A checkbox associated with the <TriStateCheckbox />.

Props

Name	Type	Required	Description
id	string	✅	A unique id. Also passed to <TriStateContext /> in controls array.
checked	boolean	❌	The state of the checkbox.
render	Function	❌	A function used to render the checkbox. The current state is passed as the boolean prop checked.

---

Contributing

This project is open to and encourages contributions! Feel free to discuss any bug fixes/features in the issues. If you wish to work on this project:

1. Fork this project
2. Create a branch (git checkout -b new-branch)
3. Commit your changes (git commit -am 'add new feature')
4. Push to the branch (git push origin new-branch)
5. Submit a pull request!