@accessible/checkbox NPM

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

import {Checkbox, Checkmark} from '@accessible/checkbox'

const MyCheckbox = () => (
  <label className='my-checkbox'>
    <Checkbox name='my-field-name'>
      <span className='my-checkbox'>
        <Checkmark checkedClass='checked' uncheckedClass='unchecked'>
          <span className='checkmark' />
        </Checkmark>
      </span>
    </Checkbox>
    Check me!
  </label>
)

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 <input>. 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 <Checkbox> is in a checked state. It must be a child of a <Checkbox>.

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 <Checkbox> is in an unchecked state. It must be a child of a <Checkbox>.

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 <Checkbox> between checked and unchecked states. It must be a child of a <Checkbox>.

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 for the nearest <Checkbox> parent.

CheckboxContextValue

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
}