Checkbox when each option can be selected independently. For a mutually exclusive choice, use RadioGroup.
Uncontrolled state
uncheckedValue if the form should also submit a value when it is unchecked.
Controlled and indeterminate states
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.