Kaleidoscope | Checkbox

Checkbox

Useful for when you want to select zero or more options from a list.

Default

What you get out of the box with this component:

Editable example
() => {
  const [checked, setChecked] = React.useState(false)
  return (
    <Checkbox
      id="abc123"
      label="Sign up for our email newsletter"
      checked={checked}
      onChange={() => setChecked(!checked)}
    />
  )
}

Disabled variant

To disable a checkbox, preventing user interaction, use the disabled prop.

Editable example
() => {
  const [checked, setChecked] = React.useState(false)
  return (
    <Checkbox
      id="abc123"
      label="The information I have provided is the truth and nothing but the truth."
      checked={checked}
      onChange={() => setChecked(!checked)}
      disabled
    />
  )
}

Size variants

We support three sizes: "s" (small, the default), "m" (medium), and "l" (large). The medium and large variants both have a "blue" selected color.

Use the large variant for selection of larger interface elements such as .

Editable example
() => {
  const [checked, setChecked] = React.useState(false)
  return (
    <Stack gap="s">
      {["s", "m", "l"].map((size) => (
          <Checkbox
            key={size}
            id={`size-${size}`}
            label={`Size "${size}"`}
            checked={checked}
            onChange={() => setChecked(!checked)}
            size={size}
          />
      ))}
    </Stack>
  )
}

Indeterminate (mixed) state

The checked prop also accepts "mixed" to represent a partially-selected or indeterminate state — useful for "select all" checkboxes where only some children are checked.

Editable example
() => {
  const [checked, setChecked] = React.useState("mixed")
  return (
    <Checkbox
      id="mixed-example"
      label="Select all items"
      checked={checked}
      onChange={(newChecked) => setChecked(newChecked)}
    />
  )
}

Error state

Use the error prop to highlight the checkbox with a validation error message.

Editable example
() => {
  const [checked, setChecked] = React.useState(false)
  return (
    <Checkbox
      id="error-example"
      label="I agree to the terms and conditions"
      checked={checked}
      onChange={() => setChecked(!checked)}
      error={!checked ? "You must agree to continue" : undefined}
    />
  )
}

Theming

We also support a dark theme for all variants:

Editable example
() => {
  const [checked, setChecked] = React.useState(false)

  return (
    <Card theme={CardTheme.Dark}>
      <div className="space-inset-m">
        <h3>Packing list</h3>
        <Checkbox
          size="m"
          theme="dark"
          id="abc123"
          label="Torch"
          checked={checked}
          onChange={() => setChecked(!checked)}
        />
      </div>
    </Card>
  )
}

onChange signature

The onChange callback receives three arguments:

onChange: (checked: boolean, id: string, event: MouseEvent<HTMLElement>) => void

checked — the new checked state
id — the checkbox's id prop, useful when handling multiple checkboxes with a single handler
event — the underlying mouse event

Best practices

Use a RadioButtonGroup when only one option can be selected from a list
For turning a single option on or off, use a Toggle
For selecting one item from a set of options with small labels or icons, use a

Accessibility

A label is always required to support users with screen-readers; if you don't want it to be visible, use the labelHidden prop