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

Usage

Uncontrolled state

Use defaultChecked to set the initial checked state. The checkbox owns subsequent changes.
A checked, named checkbox contributes its value to a form. Set uncheckedValue if the form should also submit a value when it is unchecked.

Appearance and interaction

Compare checked, indeterminate, and disabled states, then choose the color, size, shape, and variant independently. The enabled examples can be toggled. 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.

Controlled state

Pass checked and update it with onCheckedChange to own the same preference in React state. The callback receives the next boolean and event details.

Indeterminate state

An indeterminate checkbox represents a partial selection. Derive it from the child options independently of the checkbox’s checked state.

Parts and custom content

Checkbox assembles the styled root and its default check and indeterminate icons. Use Checkbox.Root with Checkbox.Indicator to own the indicator content. Root owns state and box appearance; Indicator renders the content you supply.
CheckboxRootProps and CheckboxIndicatorProps are public types exported from twenty-ui/primitives/input. Both parts accept native attributes, handlers, refs, render, and state-based className and style callbacks. Root’s ref targets the visible control; inputRef targets the native input. The part ref targets its rendered element. Pass nativeButton with render={<button />} when replacing Root with a button. Appearance props belong on Root; explicit classes and styles are merged with the defaults. Indicator receives checked and indeterminate state, including transition state. Set keepMounted to retain an unchecked indicator in the DOM; the default styling hides it with opacity. Override its style or className for custom transitions. The callable assembly and its CheckboxProps type remain supported. Replace the assembly with Root and its part when supplying custom icons instead of appending another part to the assembly’s children. For controlled form reset, handle the form’s onReset and restore checked to your initial value. Base UI 1.8 does not restore uncontrolled component state on native form reset. required, form, value, and uncheckedValue keep the upstream native input behavior.

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 and a hover background around the box.
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.
"round" | "square"
default:"square"
Corner shape of the box.
"md" | "sm"
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”.
"outline" | "soft" | "solid"
default:"solid"
Visual style of the box: filled, outlined, or tinted.

Checkbox.Root

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 and a hover background around the box.
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.
"round" | "square"
default:"square"
Corner shape of the box.
"md" | "sm"
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”.
"outline" | "soft" | "solid"
default:"solid"
Visual style of the box: filled, outlined, or tinted.

Checkbox.Indicator

string | ((state: CheckboxIndicatorState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
boolean
default:"false"
Whether to keep the element in the DOM when the checkbox is not checked.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CheckboxIndicatorState>
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.
CSSProperties | ((state: CheckboxIndicatorState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.