Checkbox

An easily stylable checkbox component.

Enable notifications

Usage guidelines

Form controls must have an accessible name: It can be created using a <label> element or the Field component. See Labeling a checkbox and the forms guide.

Anatomy

Import the component and assemble its parts:

Anatomy

import { Checkbox } from '@base-ui/react/checkbox';

<Checkbox.Root>
  <Checkbox.Indicator />
</Checkbox.Root>;

Examples

Labeling a checkbox

An enclosing <label> is the simplest labeling pattern:

Wrapping a label around a checkbox

<label>
  <Checkbox.Root />
  Accept terms and conditions
</label>

Rendering as a native button

By default, <Checkbox.Root> renders a <span> element to support enclosing labels. Prefer rendering the checkbox as a native button when using sibling labels (htmlFor/id).

Sibling label pattern with a native button

<div>
  <label htmlFor="notifications-checkbox">Enable notifications</label>
  <Checkbox.Root id="notifications-checkbox" nativeButton render={<button />}>
    <Checkbox.Indicator />
  </Checkbox.Root>
</div>

Native buttons with wrapping labels are supported by using the render callback to avoid invalid HTML, so the hidden input is placed outside the label:

Render callback

<Checkbox.Root
  nativeButton
  render={(buttonProps) => (
    <label>
      <button {...buttonProps} />
      Enable notifications
    </label>
  )}
/>

Form integration

Use Field to handle label associations and form integration:

Using Checkbox in a form

<Form>
  <Field.Root name="stayLoggedIn">
    <Field.Label>
      <Checkbox.Root />
      Stay logged in for 7 days
    </Field.Label>
  </Field.Root>
</Form>

API reference

Root

Name	Type	Default	Description
`id`Optional	`string \| undefined`	—	The id of the input element.
`name`Optional	`string \| undefined`	`undefined`	Identifies the field when a form is submitted.
`checked`Optional	`boolean \| undefined`	`undefined`	Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the `defaultChecked` prop instead.
`defaultChecked`Optional	`boolean \| undefined`	`false`	Whether the checkbox is initially ticked. To render a controlled checkbox, use the `checked` prop instead.
`disabled`Optional	`boolean \| undefined`	`false`	Whether the component should ignore user interaction.
`readOnly`Optional	`boolean \| undefined`	`false`	Whether the user should be unable to tick or untick the checkbox.
`required`Optional	`boolean \| undefined`	`false`	Whether the user must tick the checkbox before submitting a form.
`indeterminate`Optional	`boolean \| undefined`	`false`	Whether the checkbox is in a mixed state: neither ticked, nor unticked.
`inputRef`Optional	`React.Ref<HTMLInputElement> \| undefined`	—	A ref to access the hidden `<input>` element.
`parent`Optional	`boolean \| undefined`	`false`	Whether the checkbox controls a group of child checkboxes. Must be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group).
`uncheckedValue`Optional	`string \| undefined`	—	The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.
`value`Optional	`string \| undefined`	—	The value of the selected checkbox.

Indicator

Name	Type	Default	Description
`keepMounted`Optional	`boolean \| undefined`	`false`	Whether to keep the element in the DOM when the checkbox is not checked.

Checkbox

Usage guidelines

Anatomy

Examples

Labeling a checkbox

Rendering as a native button

Form integration

API reference

Root

Indicator

On this page