https://github.com/shwilliam/react-tri-state-checkbox
☑ A mixed-state checkbox for React w/ TypeScript support
https://github.com/shwilliam/react-tri-state-checkbox
checkbox component mixed-state react tri-state w3c wai-aria
Last synced: about 2 months ago
JSON representation
☑ A mixed-state checkbox for React w/ TypeScript support
- Host: GitHub
- URL: https://github.com/shwilliam/react-tri-state-checkbox
- Owner: shwilliam
- License: mit
- Created: 2019-08-10T02:25:50.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2022-02-12T11:43:58.000Z (over 3 years ago)
- Last Synced: 2025-03-17T00:38:22.827Z (2 months ago)
- Topics: checkbox, component, mixed-state, react, tri-state, w3c, wai-aria
- Language: TypeScript
- Homepage: https://codesandbox.io/s/react-tri-state-checkbox-demo-8j7mo?fontsize=14
- Size: 173 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# react-tri-state-checkbox
> A mixed-state checkbox for React based on the WAI-ARIA Authoring Practices's [tri-state checkbox](https://www.w3.org/TR/wai-aria-practices-1.1/#checkbox).
> For more details see [this specification](https://www.w3.org/TR/wai-aria-practices-1.1/#checkbox).
[](https://codesandbox.io/s/react-tri-state-checkbox-demo-8j7mo?fontsize=14)
---
## Installation
```shell
$ npm i react-tri-state-checkbox
```
---
## Usage
The following example demonstrates how the `react-tri-state-checkbox` components work together in an accessible example:
```jsx
import React from 'react'
import {
Checkbox,
TriStateCheckbox,
TriStateContext,
} from 'react-tri-state-checkbox'
import 'react-tri-state-checkbox/dist/styles.css'
const CondimentsSelect = () => (
Sandwich Condiments
All condiments
{/* checked by default */}
Lettuce
Tomato
Mustard
)
```
Note: For details about accessibility considerations please see [this](https://www.w3.org/TR/wai-aria-practices-1.1/#checkbox) document by the W3C detailing proper implementation.
### ``
A context wrapper that handles checkbox state changes. Must wrap `` and ``.
#### Props
| Name | Type | Required | Description |
| -------- | ----- | :------: | ------------------------------------ |
| controls | Array | ✅ | An array of controlled checkbox ids. |
### ``
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:
```js
import 'react-tri-state-checkbox/styles/checkbox.css'
```
### ``
A checkbox associated with the ``.
#### Props
| Name | Type | Required | Description |
| ------- | -------- | :------: | -------------------------------------------------------------------------------------------------- |
| id | string | ✅ | A unique `id`. Also passed to `` 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](https://github.com/shwilliam/react-tri-state-checkbox/issues). If you wish to work on this project:
1. Fork [this project](https://github.com/shwilliam/react-tri-state-checkbox)
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!](https://github.com/shwilliam/react-tri-state-checkbox/pull/new/master)