Checkbox

Cross-browser, cross-device checkbox built on React Aria, standalone or grouped into a managed CheckboxGroup.

Overview

<Checkbox> replaces the browser's default checkbox for selecting one or several options in a list. It renders the wrapper-based .check-input markup nested inside a single <label> — passing label produces an accessible, fully-clickable control with no extra markup.

<Checkbox> is built on React Aria for keyboard and screen-reader support. It works standalone, or inside a <CheckboxGroup> to manage a set of related checkboxes as a single array of selected values.

Checks

Default checkboxChecked checkbox

import { Checkbox } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Checkbox id="flexCheckDefault" label="Default checkbox" />
      <Checkbox id="flexCheckChecked" label="Checked checkbox" defaultSelected />
    </>
  )
}

Indeterminate

A checkbox renders the :indeterminate pseudo-class when indeterminate is set manually.

Indeterminate checkbox

import { Checkbox } from '@chassis-ui/react'

export const Example = () => {
  return <Checkbox id="flexCheckIndeterminate" label="Indeterminate checkbox" indeterminate />
}

Disabled

Set disabled and the associated <label> styles to a lighter context to indicate the input's state.

Disabled checkboxDisabled checked checkbox

import { Checkbox } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Checkbox label="Disabled checkbox" disabled />
      <Checkbox label="Disabled checked checkbox" defaultSelected disabled />
    </>
  )
}

Default (stacked)

Any number of checkboxes that are immediate siblings stack vertically with appropriate spacing by default.

Default checkboxDisabled checkbox

import { Checkbox } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Checkbox id="defaultCheck1" label="Default checkbox" />
      <Checkbox id="defaultCheck2" label="Disabled checkbox" disabled />
    </>
  )
}

Inline

Wrap checkboxes with the d-flex and gap-md flex utilities to lay them out on the same horizontal row.

123 (disabled)

import { Checkbox } from '@chassis-ui/react'

export const Example = () => {
  return (
    <div className="d-flex gap-md">
      <Checkbox id="inlineCheckbox1" value="option1" label="1" />
      <Checkbox id="inlineCheckbox2" value="option2" label="2" />
      <Checkbox id="inlineCheckbox3" value="option3" label="3 (disabled)" disabled />
    </div>
  )
}

Sizing

Set size to "sm" or "lg" to change a checkbox's size.

Large checkboxDefault checkboxSmall checkbox

import { Checkbox } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Checkbox size="lg" id="checkLarge" label="Large checkbox" />
      <Checkbox id="checkMedium" label="Default checkbox" />
      <Checkbox size="sm" id="checkSmall" label="Small checkbox" />
    </>
  )
}

Context colors

Set color to color the check indicator with any of the Chassis contextual colors.

Secondary checkbox

import { Checkbox } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Checkbox color="secondary" id="checkSecondary" label="Secondary checkbox" defaultSelected />
  )
}

Without labels

An accessible name is still required for assistive technologies when no visible label is rendered — provide one via aria-label.

import { Checkbox } from '@chassis-ui/react'

export const Example = () => {
  return <Checkbox id="checkboxNoLabel" value="" aria-label="..." />
}

Toggle buttons

Set the button prop on <Checkbox> to render a button-like toggle instead of the default check mark. Toggle buttons can be grouped in a button group.

Single toggle

import { Checkbox } from '@chassis-ui/react'

export const Example = () => {
  return <Checkbox button={{ color: 'primary' }} id="button-check" label="Single toggle" />
}

Checked

import { Checkbox } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Checkbox button={{ color: 'primary' }} id="button-check-2" label="Checked" defaultSelected />
  )
}

Disabled

import { Checkbox } from '@chassis-ui/react'

export const Example = () => {
  return <Checkbox button={{ color: 'primary' }} id="button-check-3" label="Disabled" disabled />
}

Outlined styles

button accepts the same variant values as <Button>, including outline.

Single toggle

Checked

import { Checkbox } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <div>
        <Checkbox
          button={{ color: 'primary', variant: 'outline' }}
          id="button-check-outlined"
          label="Single toggle"
        />
      </div>
      <div>
        <Checkbox
          button={{ color: 'secondary', variant: 'outline' }}
          id="button-check-2-outlined"
          label="Checked"
          defaultSelected
        />
      </div>
    </>
  )
}

Groups

<CheckboxGroup> manages a set of related checkboxes as a single array of selected values, with an optional shared description and validation feedback.

NotificationsEmailSMSPush

Choose which notifications you'd like to receive.

import { Checkbox, CheckboxGroup } from '@chassis-ui/react'

export const Example = () => {
  return (
    <CheckboxGroup
      label="Notifications"
      description="Choose which notifications you'd like to receive."
      defaultValue={['email']}
    >
      <Checkbox value="email" label="Email" />
      <Checkbox value="sms" label="SMS" />
      <Checkbox value="push" label="Push" />
    </CheckboxGroup>
  )
}

Orientation

Like <RadioGroup>, <CheckboxGroup> accepts an orientation property to lay its checkboxes out on the same horizontal row instead of stacking them.

Notifications

EmailSMSPush

import { Checkbox, CheckboxGroup } from '@chassis-ui/react'

export const Example = () => {
  return (
    <CheckboxGroup label="Notifications" defaultValue={['email']} orientation="horizontal">
      <Checkbox value="email" label="Email" />
      <Checkbox value="sms" label="SMS" />
      <Checkbox value="push" label="Push" />
    </CheckboxGroup>
  )
}

API

Checkbox

Prop	Type	Default
`button?`	`ButtonObject`	—
Create button-like checkboxes.
`className?`	`string`	—
A string of all className you want applied to the component.
`color?`	`ContextColor`	—
Sets the color of the check indicator to one of Chassis context colors. Ignored when `button` is set.
`defaultSelected?`	`boolean`	—
Whether the checkbox is selected, uncontrolled. Ignored when rendered inside a `<CheckboxGroup>` — the group's `value`/`defaultValue` owns selection there.
`id?`	`string`	—
The id global attribute defines an identifier (ID) that must be unique in the whole document.
`indeterminate?`	`boolean`	—
Checkbox indeterminate property.
`invalid?`	`boolean`	—
Set component validation state to invalid. Left unset, the component shows as invalid by itself from a submit it held back (an empty `required` one, say) until it no longer would, or its form is reset. Set it, to `false` too, and it alone decides.
`isSelected?`	`boolean`	—
Whether the checkbox is selected, controlled. Ignored when rendered inside a `<CheckboxGroup>` — the group's `value`/`defaultValue` owns selection there.
`label?`	`ReactNode`	—
The element represents a caption for a component. Children are accepted as an alias for this prop — `label` wins when both are given. react-aria, which backs this component, calls the same thing `children`; this package renames it to `label`, and honouring both means the shape React developers reach for first still names the control instead of silently producing an unlabelled one.
`onChange?`	`((isSelected: boolean) => void)`	—
Callback fired when the selected state changes. Ignored when rendered inside a `<CheckboxGroup>` — use the group's `onChange` instead.
`size?`	`"sm" \| "lg"`	—
Size the component sm or lg.
`valid?`	`boolean`	—
Set component validation state to valid.
`value?`	`string`	—
The value of the checkbox, used when submitting an HTML form. Required when rendered inside a `<CheckboxGroup>` — it identifies this item within the group's selected values.

CheckboxGroup

Prop	Type	Default
`children`	`ReactNode`	—
One or more `<Checkbox>` elements.
`className?`	`string`	—
A string of all className you want applied to the component.
`defaultValue?`	`string[]`	—
The selected values, uncontrolled.
`description?`	`ReactNode`	—
A description for the group, rendered below the options.
`disabled?`	`boolean`	—
Disables every checkbox in the group.
`errorMessage?`	`ReactNode`	—
An error message for the group, rendered below the options when `invalid` is set, and after a submit the group held back, until it no longer would.
`form?`	`string`	—
The id of the `<form>` the group belongs to, for a group rendered outside it. Reaches every checkbox; a `Checkbox` with its own `form` keeps it.
`invalid?`	`boolean`	—
Set group validation state to invalid. Left unset, the group shows as invalid by itself from a submit it held back (an empty `required` one, say) until it no longer would, or its form is reset. Set it, to `false` too, and it alone decides.
`label?`	`ReactNode`	—
The group's caption, rendered as a `<legend>`.
`name?`	`string`	—
The name for the group, used for native form submission.
`onChange?`	`((value: string[]) => void)`	—
Callback fired when the selected values change.
`orientation?`	`"horizontal" \| "vertical"`	—
Lay the group's checkboxes out on the same horizontal row instead of stacking them.
`required?`	`boolean`	—
Requires at least one checkbox of the group. While none is selected each carries the native `required`, so a form isn't submitted until one is; a `Checkbox` with its own `required` stays required whatever the others are.
`valid?`	`boolean`	—
Set group validation state to valid.
`value?`	`string[]`	—
The selected values, controlled.