An open API service indexing awesome lists of open source software.

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: 4 months ago
JSON representation

🅰 An accessible and versatile checkbox component for React

Awesome Lists containing this project

README

        





<Checkbox>




Bundlephobia


Types


Code coverage


Build status


NPM Version


MIT License

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