Checkbox

An easily stylable checkbox component.

Enable notifications

import * as React from 'react';
import { Checkbox } from '@base-ui-components/react/checkbox';
import styles from './index.module.css';

export default function ExampleCheckbox() {
  return (
    <label className={styles.Label}>
      <Checkbox.Root defaultChecked className={styles.Checkbox}>
        <Checkbox.Indicator className={styles.Indicator}>
          <CheckIcon className={styles.Icon} />
        </Checkbox.Indicator>
      </Checkbox.Root>
      Enable notifications
    </label>
  );
}

function CheckIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg fill="currentcolor" width="10" height="10" viewBox="0 0 10 10" {...props}>
      <path d="M9.1603 1.12218C9.50684 1.34873 9.60427 1.81354 9.37792 2.16038L5.13603 8.66012C5.01614 8.8438 4.82192 8.96576 4.60451 8.99384C4.3871 9.02194 4.1683 8.95335 4.00574 8.80615L1.24664 6.30769C0.939709 6.02975 0.916013 5.55541 1.19372 5.24822C1.47142 4.94102 1.94536 4.91731 2.2523 5.19524L4.36085 7.10461L8.12299 1.33999C8.34934 0.993152 8.81376 0.895638 9.1603 1.12218Z" />
    </svg>
  );
}

Anatomy

Import the component and assemble its parts:

Anatomy

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

undefined

Name: name
Description: Identifies the field when a form is submitted.
Type: string | undefined
Default: undefined

defaultChecked

boolean

false

Name: defaultChecked
Description: Whether the checkbox is initially ticked.

To render a controlled checkbox, use the checked prop instead.
Type: boolean | undefined
Default: false

checked

boolean

undefined

Name: checked
Description: Whether the checkbox is currently ticked.

To render an uncontrolled checkbox, use the defaultChecked prop instead.
Type: boolean | undefined
Default: undefined

onCheckedChange

function

—

Name: onCheckedChange
Description: Event handler called when the checkbox is ticked or unticked.
Type: | (( checked: boolean, eventDetails: Checkbox.Root.ChangeEventDetails, ) => void) | undefined

indeterminate

boolean

false

Name: indeterminate
Description: Whether the checkbox is in a mixed state: neither ticked, nor unticked.
Type: boolean | undefined
Default: false

value

string

—

Name: value
Description: The value of the selected checkbox.
Type: string | undefined

nativeButton

boolean

true

Name: nativeButton
Description: Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (e.g. <div>).
Type: boolean | undefined
Default: true

parent

boolean

false

Name: parent
Description: Whether the checkbox controls a group of child checkboxes.

Must be used in a Checkbox Group.
Type: boolean | undefined
Default: false

disabled

boolean

false

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean | undefined
Default: false

readOnly

boolean

false

Name: readOnly
Description: Whether the user should be unable to tick or untick the checkbox.
Type: boolean | undefined
Default: false

required

boolean

false

Name: required
Description: Whether the user must tick the checkbox before submitting a form.
Type: boolean | undefined
Default: false

inputRef

Ref<HTMLInputElement>

—

Name: inputRef
Description: A ref to access the hidden <input> element.
Type: React.Ref<HTMLInputElement> | undefined

id

string

—

Name: id
Description: The id of the input element.
Type: string | undefined

className

string | function

—

Name: className
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

—

Name: render
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).

Attribute	Description
`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

—

Name: className
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

false

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

render

ReactElement | function

—

Name: render
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.

Attribute	Description
`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.

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>