https://github.com/accessible-ui/checkbox
🅰 An accessible and versatile checkbox component for React
https://github.com/accessible-ui/checkbox
a11y a11y-checkbox a11y-switch aria aria-checkbox aria-switch checkbox checkbox-component react switch switch-component swithc
Last synced: 5 months ago
JSON representation
🅰 An accessible and versatile checkbox component for React
- Host: GitHub
- URL: https://github.com/accessible-ui/checkbox
- Owner: accessible-ui
- License: mit
- Created: 2019-12-13T00:36:00.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T02:20:54.000Z (over 2 years ago)
- Last Synced: 2025-01-01T09:27:22.693Z (6 months ago)
- Topics: a11y, a11y-checkbox, a11y-switch, aria, aria-checkbox, aria-switch, checkbox, checkbox-component, react, switch, switch-component, swithc
- Language: TypeScript
- Homepage: https://codesandbox.io/s/accessiblecheckbox-examples-epc8b
- Size: 798 KB
- Stars: 5
- Watchers: 2
- Forks: 3
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
<Checkbox>
npm i @accessible/checkbox
An accessible checkbox component for React. This library allows you to create
your own a checkbox with your own styles while maintaining the ability to
focus and update a checkbox input with the keyboard.
## Quick Start
[Check out the example on **CodeSandbox**](https://codesandbox.io/s/accessiblecheckbox-examples-epc8b)
```jsx harmony
import {Checkbox, Checkmark} from '@accessible/checkbox'
const MyCheckbox = () => (
Check me!
)
```
## API
### <Checkbox>
Creates a visually hidden checkbox input that is focusable and accessible via keyboard navigation.
All props passed to this component are applied to the ``. This also creates a context
provider enabling the other components in this library to access the checkbox's state
deep in the tree.
#### Props
| Prop | Type | Default | Required? | Description |
| -------------- | --------------------------- | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| checked | `boolean` | `undefined` | No | Makes the checkbox a controlled component which can no longer be updated with `check`, `uncheck`, and `toggle` controls. |
| defaultChecked | `boolean` | `undefined` | No | Set this to `true` to make the checkbox `checked` by default. |
| onChange | `(checked: boolean) => any` | `undefined` | No | Called each time the `checked` state changes. |
| children | `React.ReactNode` | `undefined` | No | Your custom styled checkbox. |
### <Checkmark>
A convenient component for conditionally adding class names and styles when the component is checked/unchecked.
#### Props
| Prop | Type | Default | Required? | Description |
| -------------- | --------------------- | ----------- | --------- | -------------------------------------------------------------------------------------- |
| uncheckedClass | `string` | `undefined` | No | This class name will be applied to the child element when the checkbox is `unchecked`. |
| checkedClass | `string` | `undefined` | No | This class name will be applied to the child element when the checkbox is `checked`. |
| uncheckedStyle | `React.CSSProperties` | `undefined` | No | These styles will be applied to the child element when the checkbox is `unchecked`. |
| checkedStyle | `React.CSSProperties` | `undefined` | No | These styles name will be applied to the child element when the checkbox is `checked`. |
| children | `React.ReactNode` | `undefined` | Yes | The child you wish to render when the checkbox is checked. |
### <Checked>
The child of this component will only render when the `` is in
a `checked` state. It must be a child of a ``.
#### Props
| Prop | Type | Default | Required? | Description |
| -------- | ----------------- | ----------- | --------- | ---------------------------------------------------------- |
| children | `React.ReactNode` | `undefined` | Yes | The child you wish to render when the checkbox is checked. |
### <Unchecked>
The child of this component will only render when the `` is in
an `unchecked` state. It must be a child of a ``.
#### Props
| Prop | Type | Default | Required? | Description |
| -------- | ----------------- | ----------- | --------- | ------------------------------------------------------------ |
| children | `React.ReactNode` | `undefined` | Yes | The child you wish to render when the checkbox is unchecked. |
### <Toggle>
This component clones its child and adds an `onClick` handler to toggle the `` between
`checked` and `unchecked` states. It must be a child of a ``.
#### Props
| Prop | Type | Default | Required? | Description |
| -------- | ----------------- | ----------- | --------- | ------------------------------------------------------------ |
| children | `React.ReactNode` | `undefined` | Yes | The child you wish to render when the checkbox is unchecked. |
### useCheckbox()
A React hook that returns the [`CheckboxContextValue`](#checkboxcontextvalue) for the nearest `` parent.
### CheckboxContextValue
```typescript
interface CheckboxContextValue {
// Does the checkbox have a `checked` property?
checked: boolean
// Is the checkbox currently focused?
focused: boolean
// Is the checkbox currently disabled?
disabled: boolean
// Checks the checkbox
check: () => void
// Unchecks the checkbox
uncheck: () => void
// Toggles the checkbox `checked` property
toggle: () => void
}
```
## LICENSE
MIT