Skip to content

accessible-ui/checkbox

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

39 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation


<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

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
}

LICENSE

MIT