Skip to main content
Use Checkbox when each option can be selected independently. For a mutually exclusive choice, use RadioGroup.

Uncontrolled state

A checked, named checkbox contributes its value to a form. Set uncheckedValue if the form should also submit a value when it is unchecked.

Controlled and indeterminate states

The indeterminate state represents a partial selection; the application derives it from the child options. onCheckedChange receives the next boolean and event details.

Appearance and interaction

Tab focuses the checkbox and Space toggles it. Clicking its label also toggles it. Use disabled to prevent interaction, or readOnly when the value should remain unchanged while the control stays focusable. Keep meaning in the label rather than communicating it through color alone.

Props

The reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.
boolean
Whether the checkbox is currently ticked.To render an uncontrolled checkbox, use the defaultChecked prop instead.
string | ((state: CheckboxRootState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
"accent" | "success" | "warning"
default:"accent"
Color used while the checkbox is checked or indeterminate.
boolean
default:"false"
Whether the checkbox is initially ticked.To render a controlled checkbox, use the checked prop instead.
boolean
default:"false"
Whether the component should ignore user interaction.
string
Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.
boolean
default:"true"
Adds padding around the box and a hover background. Disable it for a compact checkbox inside another interactive element.
string
The id of the input element.
boolean
default:"false"
Whether the checkbox is in a mixed state: neither ticked, nor unticked.
Ref<HTMLInputElement>
A ref to access the hidden <input> element.
string
Identifies the field when a form is submitted.
boolean
default:"false"
Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.
((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)
Event handler called when the checkbox is ticked or unticked.
boolean
default:"false"
Whether the checkbox controls a group of child checkboxes.Must be used in a Checkbox Group.
boolean
default:"false"
Whether the user should be unable to tick or untick the checkbox.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CheckboxRootState>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
boolean
default:"false"
Whether the user must tick the checkbox before submitting a form.
"square" | "round"
default:"square"
Corner shape of the box.
"sm" | "md"
default:"sm"
Visual size of the checkbox.
CSSProperties | ((state: CheckboxRootState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
string
The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.
string
The checkbox’s value. Identifies it within a Checkbox Group, falling back to name when omitted. When submitting a form, a checked box submits value; with no value, it submits the native “on”.
"solid" | "outline" | "soft"
default:"solid"
Visual style of the box: filled, outlined, or tinted.