Checkbox

A control element that allows for multiple selections within a set.

Label

You can explore the checkbox component in the following curated examples.

Checkbox Group

Render a Checkbox Group with multiple options.

Anatomy

<Checkbox.Root>
  <Checkbox.Control>
    <Checkbox.Indicator />
  </Checkbox.Control>
  <Checkbox.Label />
  <Checkbox.HiddenInput />
</Checkbox.Root>

Examples

Default Checked

Use the defaultChecked prop to set the initial checked state in an uncontrolled manner. The checkbox will manage its own state internally.

Controlled

Use the checked and onCheckedChange props to programatically control the checkbox's state.

Root Provider

An alternative way to control the checkbox is to use the RootProvider component and the useCheckbox hook. This way you can access the state and methods from outside the component.

Disabled

Use the disabled prop to make the checkbox non-interactive.

Indeterminate

Use the indeterminate prop to create a checkbox in an indeterminate state (partially checked).

Field

The checkbox integrates smoothly with the Field component to handle form state, helper text, and error text for proper accessibility.

Form

Pass the name and value props to the Checkbox.Root component to make the checkbox part of a form. The checkbox's value will be submitted with the form when the user submits it.

Context

Use the Checkbox.Context component to access the checkbox's state and methods.

Group

Use the Checkbox.Group component to manage a group of checkboxes. The Checkbox.Group component manages the state of the checkboxes and provides a way to access the checked values.

Controlled Group

Use the value and onValueChange props to programmatically control the checkbox group's state. This example demonstrates how to manage selected checkboxes in an array and display the current selection.

Group Provider

Use the useCheckboxGroup hook to create the checkbox group store and pass it to the Checkbox.GroupProvider component. This provides maximum control over the group programmatically, similar to how RootProvider works for individual checkboxes.

Invalid

Use the invalid prop on Checkbox.Group to mark the entire group as invalid for validation purposes. This applies the invalid state to all checkboxes within the group.

Select All

Implement a "select all" checkbox that controls all checkboxes within a group. The parent checkbox automatically shows an indeterminate state when some (but not all) items are selected, and becomes fully checked when all items are selected.

Group Form

Use the Checkbox.Group component within a form to handle multiple checkbox values with form submission. The name prop ensures all selected values are collected as an array when the form is submitted using FormData.getAll().

Fieldset

Use the Fieldset component with Checkbox.Group to provide semantic grouping with legend, helper text, and error text support.

Guides

asChild Behavior

The Checkbox.Root element of the checkbox is a label element. This is because the checkbox is a form control and should be associated with a label to provide context and meaning to the user. Otherwise, the HTML and accessibility structure will be invalid.

If you need to use the asChild property, make sure that the label element is the direct child of the Checkbox.Root component.

API Reference

Props

Root

Renders a <label> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`checked`		`CheckedState` The controlled checked state of the checkbox
`defaultChecked`		`CheckedState` The initial checked state of the checkbox when rendered. Use when you don't need to control the checked state of the checkbox.
`disabled`		`boolean` Whether the checkbox is disabled
`form`		`string` The id of the form that the checkbox belongs to.
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string; hiddenInput: string; control: string; label: string }>` The ids of the elements in the checkbox. Useful for composition.
`invalid`		`boolean` Whether the checkbox is invalid
`name`		`string` The name of the input field in a checkbox. Useful for form submission.
`onCheckedChange`		`(details: CheckedChangeDetails) => void` The callback invoked when the checked state changes.
`readOnly`		`boolean` Whether the checkbox is read-only
`required`		`boolean` Whether the checkbox is required
`value`	`'on'`	`string` The value of checkbox input. Useful for form submission.

Attribute	Description
`[data-active]`	Present when active or pressed
`[data-focus]`	Present when focused
`[data-focus-visible]`	Present when focused with keyboard
`[data-readonly]`	Present when read-only
`[data-hover]`	Present when hovered
`[data-disabled]`	Present when disabled
`[data-state]`	"indeterminate" \| "checked" \| "unchecked"
`[data-invalid]`	Present when invalid
`[data-required]`	Present when required

Control

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-active]`	Present when active or pressed
`[data-focus]`	Present when focused
`[data-focus-visible]`	Present when focused with keyboard
`[data-readonly]`	Present when read-only
`[data-hover]`	Present when hovered
`[data-disabled]`	Present when disabled
`[data-state]`	"indeterminate" \| "checked" \| "unchecked"
`[data-invalid]`	Present when invalid
`[data-required]`	Present when required

Group

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`defaultValue`		`string[]` The initial value of `value` when uncontrolled
`disabled`		`boolean` If `true`, the checkbox group is disabled
`invalid`		`boolean` If `true`, the checkbox group is invalid
`name`		`string` The name of the input fields in the checkbox group (Useful for form submission).
`onValueChange`		`(value: string[]) => void` The callback to call when the value changes
`readOnly`		`boolean` If `true`, the checkbox group is read-only
`value`		`string[]` The controlled value of the checkbox group

GroupProvider

Renders a <div> element.

Prop	Default	Type
`value`		`UseCheckboxGroupContext`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

HiddenInput

Renders a <input> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Indicator

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`indeterminate`		`boolean`

Attribute	Description
`[data-active]`	Present when active or pressed
`[data-focus]`	Present when focused
`[data-focus-visible]`	Present when focused with keyboard
`[data-readonly]`	Present when read-only
`[data-hover]`	Present when hovered
`[data-disabled]`	Present when disabled
`[data-state]`	"indeterminate" \| "checked" \| "unchecked"
`[data-invalid]`	Present when invalid
`[data-required]`	Present when required

Label

Renders a <span> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-active]`	Present when active or pressed
`[data-focus]`	Present when focused
`[data-focus-visible]`	Present when focused with keyboard
`[data-readonly]`	Present when read-only
`[data-hover]`	Present when hovered
`[data-disabled]`	Present when disabled
`[data-state]`	"indeterminate" \| "checked" \| "unchecked"
`[data-invalid]`	Present when invalid
`[data-required]`	Present when required

RootProvider

Renders a <label> element.

Prop	Default	Type
`value`		`UseCheckboxReturn`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Context

API

Property	Type
`checked`	`boolean` Whether the checkbox is checked
`disabled`	`boolean` Whether the checkbox is disabled
`indeterminate`	`boolean` Whether the checkbox is indeterminate
`focused`	`boolean` Whether the checkbox is focused
`checkedState`	`CheckedState` The checked state of the checkbox
`setChecked`	`(checked: CheckedState) => void` Function to set the checked state of the checkbox
`toggleChecked`	`VoidFunction` Function to toggle the checked state of the checkbox

Accessibility

Complies with the Checkbox WAI-ARIA design pattern.

Keyboard Support

Key	Description
`Space`	Toggle the checkbox