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!