React-tri-state-checkbox NPM

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.

Tri-state checkbox usage gif

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`.