Checkbox

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

• View on Github
• View Core API
• View on Figma

Import

import { Checkbox } from '@pluralsight/react'

Anatomy

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

Usage

Basic Checkbox

Result

Loading...

Live Editor

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> ) }

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.

Result

Loading...

Live Editor

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

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

States

Checked

Disabled

Invalid

Read only

Required (required)

Indeterminate

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.

Example of using CSS Modules to customize the Checkbox.

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.