Skip to main content

Checkbox

Used when a user needs to select multiple values from options in a form.

Import

import { Checkbox } from '@pluralsight/react'

Anatomy

  1. Container
  2. Control
  3. Input
  4. Label

Usage

Basic Checkbox

function BasicCheckbox() {
  const [checked, setChecked] = useState(false)

  function handleChange(e) {
    setChecked(e.target.checked)
  }

  return (
    <FormControlProvider>
      <Checkbox
        checked={checked}
        id="sign_up"
        name="sign_up"
        onChange={handleChange}
      >
        Sign up for something
      </Checkbox>
    </FormControlProvider>
  )
}

Indeterminate Checkbox

To display an indeterminate state, pass the indeterminate prop along with the checked to the Checkbox component.

function IndeterminateCheckbox() {
  return (
    <FormControlProvider readOnly={true}>
      <Checkbox
        checked={true}
        id="select_all"
        indeterminate={true}
        name="select_all"
      >
        Select all
      </Checkbox>
    </FormControlProvider>
  )
}

States

Customizing

There are 3 ways to customize the Checkbox component.

1. Unused Classes

Each component layer of the Checkbox has a unused class name that can be utilized in your local CSS to customize the Checkbox at any level.

  1. pando-checkbox-container: The container element of the Checkbox.
  2. pando-checkbox-input: The input element of the Checkbox.
  3. pando-checkbox-control: The control element of the Checkbox.

2. Passing a className prop

You can pass a className prop to the Checkbox component to customize the Checkbox. This is useful if your project uses CSS Modules or a CSS-in-JS library like Emotion.

import customStyles from './customStyles.module.css'

function CustomCheckbox(props) {
  return <Checkbox className={customStyles.custom} {...props} />
}

3. Ejected Checkbox

For a low-level "ejected" approach, you can use the Headless-styles API to customize the Checkbox however you prefer while keeping the accessibility behavior.

import { getCheckboxProps } from '@pluralsight/headless-styles'

To learn more about the Headless-styles API, check out the Headless-styles documentation.

Behavior

Layout

Do use multiple Checkboxes in a vertical list.

Don't use multiple Checkboxes in a single row.

Do provide a Label with a Checkbox.

Don't use a Checkbox inline without a Label.

Usage

Do use a Checkbox for giving users an option to "opt-in" to a choice.

Don't use a Checkbox for showing/hiding content.

Interactions

Do use the indeterminate state for a parent option of a nested group.

Don't use the indeterminate state for a single option within a group.

API

Parameters

interface CheckboxProps extends InputHTMLAttributes<HTMLInputElement> {
  checked: boolean
  id: string
  indeterminate?: boolean
  name?: string
}
  1. checked: boolean - Whether the Checkbox is checked or not.
  2. id: string - The id of the Checkbox.
  3. indeterminate: boolean - Whether the Checkbox is in an indeterminate state or not.
  4. name: string - The name of the Checkbox.

Accessibility

The Pando Checkbox is fully accessible and screen-readable through the following features:

  1. The aria-invalid attribute is set to true when the input is invalid.
  2. The aria-describedby attribute is set to the id of the FieldMessage or ErrorMessage that describes the input.
  3. The aria-required attribute is set to true when the input is required.
  4. The aria-disabled attribute is set to true when the input is disabled.
  5. The aria-checked attribute is set to true when the input is checked.
  6. The aria-checked attribute is set to mixed when the input is indeterminate.
  7. The aria-hidden attribute is set to true on the input control and icon to hide it from screen readers.