Checkbox
An easily stylable checkbox component.
View as MarkdownAnatomy
Import the component and assemble its parts:
import { Checkbox } from '@base-ui-components/react/checkbox';
<Checkbox.Root>
<Checkbox.Indicator />
</Checkbox.Root>
API reference
Root
Represents the checkbox itself.
Renders a <button>
element and a hidden <input>
beside.
name
string
(default: undefined
)
string
undefined
- Name
- Description
Identifies the field when a form is submitted.
- Type
string
- Default
undefined
defaultChecked
boolean
(default: false
)
boolean
false
- Name
- Description
Whether the checkbox is initially ticked.
To render a controlled checkbox, use the
checked
prop instead.- Type
boolean
- Default
false
checked
boolean
(default: undefined
)
boolean
undefined
- Name
- Description
Whether the checkbox is currently ticked.
To render an uncontrolled checkbox, use the
defaultChecked
prop instead.- Type
boolean
- Default
undefined
onCheckedChange
function
function
- Name
- Description
Event handler called when the checkbox is ticked or unticked.
- Type
((checked: boolean, event: Event) => void)
indeterminate
boolean
(default: false
)
boolean
false
- Name
- Description
Whether the checkbox is in a mixed state: neither ticked, nor unticked.
- Type
boolean
- Default
false
value
string
string
- Name
- Description
The value of the selected checkbox.
- Type
string
nativeButton
boolean
(default: true
)
boolean
true
- Name
- Description
Whether the component renders a native
<button>
element when replacing it via therender
prop. Set tofalse
if the rendered element is not a button (e.g.<div>
).- Type
boolean
- Default
true
parent
boolean
(default: false
)
boolean
false
- Name
- Description
Whether the checkbox controls a group of child checkboxes.
Must be used in a Checkbox Group.
- Type
boolean
- Default
false
disabled
boolean
(default: false
)
boolean
false
- Name
- Description
Whether the component should ignore user interaction.
- Type
boolean
- Default
false
readOnly
boolean
(default: false
)
boolean
false
- Name
- Description
Whether the user should be unable to tick or untick the checkbox.
- Type
boolean
- Default
false
required
boolean
(default: false
)
boolean
false
- Name
- Description
Whether the user must tick the checkbox before submitting a form.
- Type
boolean
- Default
false
inputRef
Ref<HTMLInputElement>
Ref<HTMLInputElement>
- Name
- Description
A ref to access the hidden
<input>
element.- Type
Ref<HTMLInputElement>
id
string
string
- Name
- Description
The id of the input element.
- Type
string
className
string | function
string | function
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
| string
| ((state: Checkbox.Root.State) => string)
render
ReactElement | function
ReactElement | function
- Name
- Description
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.- Type
| ReactElement
| ((props: HTMLProps, state: Checkbox.Root.State) => ReactElement)
data-checked
Present when the checkbox is checked.
data-unchecked
Present when the checkbox is not checked.
data-disabled
Present when the checkbox is disabled.
data-readonly
Present when the checkbox is readonly.
data-required
Present when the checkbox is required.
data-valid
Present when the checkbox is in valid state (when wrapped in Field.Root).
data-invalid
Present when the checkbox is in invalid state (when wrapped in Field.Root).
data-dirty
Present when the checkbox's value has changed (when wrapped in Field.Root).
data-touched
Present when the checkbox has been touched (when wrapped in Field.Root).
data-filled
Present when the checkbox is checked (when wrapped in Field.Root).
data-focused
Present when the checkbox is focused (when wrapped in Field.Root).
Indicator
Indicates whether the checkbox is ticked.
Renders a <span>
element.
className
string | function
string | function
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
| string
| ((state: Checkbox.Indicator.State) => string)
keepMounted
boolean
(default: false
)
boolean
false
- Name
- Description
Whether to keep the element in the DOM when the checkbox is not checked.
- Type
boolean
- Default
false
render
ReactElement | function
ReactElement | function
- Name
- Description
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.- Type
| ReactElement
| ((props: HTMLProps, state: Checkbox.Indicator.State) => ReactElement)
data-checked
Present when the checkbox is checked.
data-unchecked
Present when the checkbox is not checked.
data-disabled
Present when the checkbox is disabled.
data-readonly
Present when the checkbox is readonly.
data-required
Present when the checkbox is required.
data-valid
Present when the checkbox is in valid state (when wrapped in Field.Root).
data-invalid
Present when the checkbox is in invalid state (when wrapped in Field.Root).
data-dirty
Present when the checkbox's value has changed (when wrapped in Field.Root).
data-touched
Present when the checkbox has been touched (when wrapped in Field.Root).
data-filled
Present when the checkbox is checked (when wrapped in Field.Root).
data-focused
Present when the checkbox is focused (when wrapped in Field.Root).
data-starting-style
Present when the checkbox indicator is animating in.
data-ending-style
Present when the checkbox indicator is animating out.
Examples
Form integration
To use a single checkbox in a form, pass the checkbox’s name
to Field
and use Field.Label
to label the control.
<Form>
<Field.Root name="stayLoggedIn">
<Field.Label>
<Checkbox.Root />
Stay logged in for 7 days
</Field.Label>
</Field.Root>
</Form>