Checkbox

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

Anatomy

To set up the checkbox correctly, you’ll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Design impact on the asChild property

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.

Examples

Learn how to use the Checkbox component in your project. Let’s take a look at the most basic example:

Controlled Checkbox

To create a controlled Checkbox component, manage the state of the checked status using the checked prop and update it when the onCheckedChange event handler is called:

Indeterminate Checkbox

In some cases, you may need a checkbox to represent a state that is neither checked nor unchecked, known as the indeterminate state. This can be achieved by setting the checked prop to indeterminate:

Render Prop Usage

For cases where you need more flexibility in rendering, the Checkbox component offers the use of a render prop. The render prop function gives you access to the checkbox’s API, allowing you to customize the checkbox control’s rendering:

API Reference

Root

PropTypeDefault
asChild
boolean
checked
CheckedState
defaultChecked
CheckedState
disabled
boolean
form
string
id
string
ids
Partial<{ root: string hiddenInput: string control: string label: string }>
invalid
boolean
name
string
onCheckedChange
(details: CheckedChangeDetails) => void
readOnly
boolean
required
boolean
value
string"on"

Control

PropTypeDefault
asChild
boolean

HiddenInput

PropTypeDefault
asChild
boolean

Indicator

PropTypeDefault
asChild
boolean
indeterminate
boolean

Label

PropTypeDefault
asChild
boolean