Checkbox

Checkbox is a form control for single and multiple selections.

Page navigation navigation

React

readyNot reviewed for a11y

Storybook|Source

Rails

readyNot reviewed for a11y

Docs|Lookbook|Source

Figma

View in Figma|

It's unlikely that you'll be rendering a single Checkbox. See the CheckboxGroup component for rendering a set of Checkboxes.

Best practices

An individual Checkbox should not have its own validation message or style. Instead, show a validation message on the CheckboxGroup. For more information, see the Validation Message section in the Forms documentation.
While there are certain use cases where an individual checkbox may be required, the most common use case is to require a selection from a CheckboxGroup. In this case, an individual checkbox button should not be marked as required, but the checkbox group should be marked as required instead. For more information, see the Required field indicator in the Forms documentation.

React examples

Default

Checkbox label

<FormControl>
  <Checkbox value="default" />
  <FormControl.Label>Checkbox label</FormControl.Label>
</FormControl>

<FormControl>
  <Checkbox value="default" />
  <FormControl.Label>Checkbox label</FormControl.Label>
</FormControl>

With a caption

Checkbox labelThis is a caption

<FormControl>
  <Checkbox value="default" />
  <FormControl.Label>Checkbox label</FormControl.Label>
  <FormControl.Caption>This is a caption</FormControl.Caption>
</FormControl>

<FormControl>
  <Checkbox value="default" />
  <FormControl.Label>Checkbox label</FormControl.Label>
  <FormControl.Caption>This is a caption</FormControl.Caption>
</FormControl>

With a leading visual

Checkbox label

<FormControl>
  <FormControl.LeadingVisual>
    <MarkGithubIcon />
  </FormControl.LeadingVisual>
  <Checkbox value="default" />
  <FormControl.Label>Checkbox label</FormControl.Label>
</FormControl>

<FormControl>
  <FormControl.LeadingVisual>
    <MarkGithubIcon />
  </FormControl.LeadingVisual>
  <Checkbox value="default" />
  <FormControl.Label>Checkbox label</FormControl.Label>
</FormControl>

In a group of Checkboxes

This example uses the CheckboxGroup component to render a set of Checkboxes.

Choices

Choice one

Choice two

Choice three

<CheckboxGroup>
  <CheckboxGroup.Label>Choices</CheckboxGroup.Label>
  <FormControl>
    <Checkbox value="one" />
    <FormControl.Label>Choice one</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="two" />
    <FormControl.Label>Choice two</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="three" />
    <FormControl.Label>Choice three</FormControl.Label>
  </FormControl>
</CheckboxGroup>

<CheckboxGroup>
  <CheckboxGroup.Label>Choices</CheckboxGroup.Label>
  <FormControl>
    <Checkbox value="one" />
    <FormControl.Label>Choice one</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="two" />
    <FormControl.Label>Choice two</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="three" />
    <FormControl.Label>Choice three</FormControl.Label>
  </FormControl>
</CheckboxGroup>

Indeterminate

Checkbox label

<FormControl>
  <Checkbox value="default" indeterminate />
  <FormControl.Label>Checkbox label</FormControl.Label>
</FormControl>

<FormControl>
  <Checkbox value="default" indeterminate />
  <FormControl.Label>Checkbox label</FormControl.Label>
</FormControl>

More code examples

See the Checkbox Storybook stories

Props

Checkbox

Name	Default	Description
checked		`boolean` Modifies true/false value of the native checkbox
defaultChecked		`boolean` Checks the input by default in uncontrolled mode
disabled		`boolean` Modifies the native disabled state of the native checkbox
indeterminate	`false`	`boolean` Applies an indeterminate state to the checkbox
onChange		`(event: React.ChangeEvent) => void` A callback function that is triggered when the checked state has been changed
validationStatus		`'error' \| 'success'` Only used to inform ARIA attributes. Individual checkboxes do not have validation styles.
value		`string` A unique value that is never shown to the user. Used during form submission and to identify which checkbox inputs are selected.
ref		`React.RefObject<HTMLInputElement>`
as	`"input"`	`React.ElementType`
sx		`SystemStyleObject`