Checkbox

An easily stylable checkbox component.

Enable notifications

import type { JSX } from '@solidjs/web';
import { Checkbox } from 'base-ui-solid/checkbox';
import styles from './index.module.css';

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

function CheckIcon(props: JSX.IntrinsicElements['svg']) {
  return (
    <svg
      width="16"
      height="16"
      viewBox="0 0 16 16"
      fill="none"
      stroke="currentColor"
      {...props}
      style={
        typeof props.style === 'string'
          ? `display: block; ${props.style}`
          : { display: 'block', ...(typeof props.style === 'object' ? props.style : {}) }
      }
    >
      <path d="m2.5 8.5 4 4 7-9" />
    </svg>
  );
}

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-solid/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 (for/id).

Sibling label pattern with a native button

<div>
  <label for="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

Represents the checkbox itself. Renders a <span> element and a hidden <input> beside.

Prop

Type

Default

namestringundefined

Identifies the field when a form is submitted.string

defaultCheckedbooleanfalse

Whether the checkbox is initially ticked. To render a controlled checkbox, use the checked prop instead.boolean

checkedbooleanundefined

Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the defaultChecked prop instead.boolean

onCheckedChangefunction—

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

indeterminatebooleanfalse

Whether the checkbox is in a mixed state: neither ticked, nor unticked.boolean

valuestring—

The checkbox’s value. Identifies it within a [Checkbox Group](/solid/components/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".string

formstring—

Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.string

nativeButtonbooleanfalse

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.boolean

parentbooleanfalse

Whether the checkbox controls a group of child checkboxes. Must be used in a [Checkbox Group](/solid/components/checkbox-group).boolean

uncheckedValuestring—

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

disabledbooleanfalse

Whether the component should ignore user interaction.boolean

readOnlybooleanfalse

Whether the user should be unable to tick or untick the checkbox.boolean

requiredbooleanfalse

Whether the user must tick the checkbox before submitting a form.boolean

inputRefJSX.Ref<HTMLInputElement>—

A ref to access the hidden <input> element.JSX.Ref<HTMLInputElement>

idstring—

The id of the input element.string

classfunction—

CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)

stylefunction—

Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)

renderfunction—

Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)

Data attributes

Name

Type

Default

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 a valid state (when wrapped in Field.Root).-

data-invalid-—

Present when the checkbox is in an 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-indeterminate-—

Present when the checkbox is in an indeterminate state.-

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 a valid state (when wrapped in Field.Root).
`data-invalid`	Present when the checkbox is in an 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-indeterminate`	Present when the checkbox is in an indeterminate state.

Root.State

type CheckboxRootState = {
  /** Whether the checkbox is currently ticked. */
  checked: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the user should be unable to tick or untick the checkbox. */
  readOnly: boolean;
  /** Whether the user must tick the checkbox before submitting a form. */
  required: boolean;
  /** Whether the checkbox is in a mixed state: neither ticked, nor unticked. */
  indeterminate: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

Root.ChangeEventReason

type CheckboxRootChangeEventReason = 'none';

Root.ChangeEventDetails

type CheckboxRootChangeEventDetails = {
  /** The reason for the event. */
  reason: 'none';
  /** The native event associated with the custom event. */
  event: Event;
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
};

Indicator

Indicates whether the checkbox is ticked. Renders a <span> element.

Prop

Type

Default

classfunction—

CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)

stylefunction—

Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)

keepMountedbooleanfalse

Whether to keep the element in the DOM when the checkbox is not checked.boolean

renderfunction—

Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)

Data attributes

Name

Type

Default

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 a valid state (when wrapped in Field.Root).-

data-invalid-—

Present when the checkbox is in an 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-indeterminate-—

Present when the checkbox is in an indeterminate state.-

data-starting-style-—

Present when the checkbox indicator begins 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 a valid state (when wrapped in Field.Root).
`data-invalid`	Present when the checkbox is in an 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-indeterminate`	Present when the checkbox is in an indeterminate state.
`data-starting-style`	Present when the checkbox indicator begins animating in.
`data-ending-style`	Present when the checkbox indicator is animating out.

Indicator.State

type CheckboxIndicatorState = {
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** Whether the checkbox is currently ticked. */
  checked: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the user should be unable to tick or untick the checkbox. */
  readOnly: boolean;
  /** Whether the user must tick the checkbox before submitting a form. */
  required: boolean;
  /** Whether the checkbox is in a mixed state: neither ticked, nor unticked. */
  indeterminate: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};