---
title: Checkbox
subtitle: An easily stylable checkbox component.
description: A high-quality, unstyled React checkbox component that is easy to customize.
---

> FineSoft Components documentation. Independent Stencil port; not the official Base UI website.
>
> React API text and `@base-ui/react` examples are upstream references. FineSoft Stencil examples use `finesoft-components`. Do not treat the two packages as interchangeable.

# Checkbox

A high-quality, unstyled React checkbox component that is easy to customize.

## Demo

### Tailwind

This example shows how to implement the component using Tailwind CSS.

```tsx
/* docs-comparison.tsx */
import { StencilComparison } from 'docs/src/components/StencilComparison';
import ReactCheckbox from './react-checkbox';
import StencilCheckbox from './stencil-checkbox';

export default function CheckboxComparison() {
  return <StencilComparison key="tailwind" component="checkbox" react={<ReactCheckbox />} stencil={<StencilCheckbox />} />;
}
```

```tsx
/* react-checkbox.tsx */
import * as React from 'react';
import { Checkbox } from '@base-ui/react/checkbox';

export default function ExampleCheckbox() {
  return (
    <label className="flex items-center gap-2 text-sm font-normal text-neutral-950 dark:text-white">
      <Checkbox.Root
        defaultChecked
        className="flex size-4 shrink-0 items-center justify-center border rounded-none p-0 border-neutral-950 bg-white text-white dark:border-white dark:bg-neutral-950 dark:text-neutral-950 data-checked:bg-neutral-950 data-checked:text-white dark:data-checked:bg-white dark:data-checked:text-neutral-950 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
      >
        <Checkbox.Indicator className="flex data-unchecked:hidden">
          <CheckIcon />
        </Checkbox.Indicator>
      </Checkbox.Root>
      Enable notifications
    </label>
  );
}

function CheckIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" {...props} style={{ display: 'block', ...props.style }}>
      <path d="m2.5 8.5 4 4 7-9" />
    </svg>
  );
}
```

```tsx
/* stencil-checkbox.tsx */
import * as React from 'react';

export default function StencilCheckbox() {
  return (
    <label className="flex items-center gap-2 text-sm font-normal text-neutral-950 dark:text-white">
      <fs-checkbox-root
        default-checked
        className="flex size-4 shrink-0 items-center justify-center border rounded-none p-0 border-neutral-950 bg-white text-white dark:border-white dark:bg-neutral-950 dark:text-neutral-950 data-checked:bg-neutral-950 data-checked:text-white dark:data-checked:bg-white dark:data-checked:text-neutral-950 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
      >
        <fs-checkbox-indicator className="[&::part(indicator)]:box-border [&::part(indicator)]:flex [&[data-unchecked]::part(indicator)]:hidden">
          <CheckIcon />
        </fs-checkbox-indicator>
      </fs-checkbox-root>
      Enable notifications
    </label>
  );
}

function CheckIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" {...props} style={{ display: 'block', ...props.style }}>
      <path d="m2.5 8.5 4 4 7-9" />
    </svg>
  );
}
```

### CSS Modules

This example shows how to implement the component using CSS Modules.

```css
/* index.module.css */
.Label {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  font-size: 0.875rem;
  line-height: 1.25rem;
  font-weight: 400;
  color: oklch(14.5% 0 0deg);

  @media (prefers-color-scheme: dark) {
    color: white;
  }
}

.Checkbox {
  box-sizing: border-box;
  display: flex;
  flex-shrink: 0;
  width: 1rem;
  height: 1rem;
  align-items: center;
  justify-content: center;
  border: 1px solid oklch(14.5% 0 0deg);
  border-radius: 0;
  background-color: white;
  color: white;
  padding: 0;
  margin: 0;

  @media (prefers-color-scheme: dark) {
    border: 1px solid white;
    background-color: oklch(14.5% 0 0deg);
    color: oklch(14.5% 0 0deg);
  }

  &[data-checked],
  &[data-indeterminate] {
    background-color: oklch(14.5% 0 0deg);
    color: white;

    @media (prefers-color-scheme: dark) {
      background-color: white;
      color: oklch(14.5% 0 0deg);
    }
  }

  &:focus-visible {
    outline: 2px solid oklch(14.5% 0 0deg);
    outline-offset: 2px;

    @media (prefers-color-scheme: dark) {
      outline-color: white;
    }
  }
}

.Indicator {
  display: flex;

  &[data-unchecked] {
    display: none;
  }
}
```

```tsx
/* docs-comparison.tsx */
import { StencilComparison } from 'docs/src/components/StencilComparison';
import ReactCheckbox from './react-checkbox';
import StencilCheckbox from './stencil-checkbox';

export default function CheckboxComparison() {
  return <StencilComparison key="css-modules" component="checkbox" react={<ReactCheckbox />} stencil={<StencilCheckbox />} />;
}
```

```tsx
/* react-checkbox.tsx */
import * as React from 'react';
import { Checkbox } from '@base-ui/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 />
        </Checkbox.Indicator>
      </Checkbox.Root>
      Enable notifications
    </label>
  );
}

function CheckIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" {...props} style={{ display: 'block', ...props.style }}>
      <path d="m2.5 8.5 4 4 7-9" />
    </svg>
  );
}
```

```tsx
/* stencil-checkbox.tsx */
import * as React from 'react';

export default function StencilCheckbox() {
  return (
    <label>
      <fs-checkbox-root default-checked>
        <fs-checkbox-indicator>
          <CheckIcon />
        </fs-checkbox-indicator>
      </fs-checkbox-root>
      Enable notifications
    </label>
  );
}

function CheckIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" {...props} style={{ display: 'block', ...props.style }}>
      <path d="m2.5 8.5 4 4 7-9" />
    </svg>
  );
}
```

## Stencil styling

`fs-checkbox-root` keeps its native control and form input in Light DOM to preserve native labels and form ownership. `fs-checkbox-indicator` uses an open ShadowRoot and exposes `::part(indicator)`; its author content remains in a native slot.

The Base UI theme is built in; set `data-fs-theme="base-ui"` on an ancestor for the default skin. Indicator classes remain on the host; use `fs-checkbox-indicator::part(indicator)` for internal styles. Checked, indeterminate, disabled and transition states are available on the host. Author inline styles still apply to the indicator container. Checkbox Group keeps its public layout and semantics in Light DOM.

## 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](/react/components/checkbox.md) and the [forms guide](/react/handbook/forms.md).

## Anatomy

Import the component and assemble its parts:

```jsx title="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:

```tsx title="Wrapping a label around a checkbox"
// @highlight
<label>
  <Checkbox.Root />
  Accept terms and conditions
  {/* @highlight */}
</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`).

```tsx title="Sibling label pattern with a native button"
<div>
  <label htmlFor="notifications-checkbox">Enable notifications</label>
  {/* @highlight-text "nativeButton" "render={<button />}" */}
  <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:

```tsx title="Render callback"
<Checkbox.Root
  nativeButton
  // @highlight-start
  render={(buttonProps) => (
    <label>
      <button {...buttonProps} />
      Enable notifications
    </label>
  )}
  {/* @highlight-end */}
/>
```

### Form integration

Use [Field](/react/components/field.md) to handle label associations and form integration:

```tsx title="Using Checkbox in a form"
<Form>
  {/* @highlight */}
  <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.

**Root Props:**

| Prop            | Type                                                                                        | Default     | Description                                                                                                                                                                                                                                                      |
| :-------------- | :------------------------------------------------------------------------------------------ | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name            | `string`                                                                                    | `undefined` | Identifies the field when a form is submitted.                                                                                                                                                                                                                   |
| defaultChecked  | `boolean`                                                                                   | `false`     | Whether the checkbox is initially ticked. To render a controlled checkbox, use the `checked` prop instead.                                                                                                                                                       |
| checked         | `boolean`                                                                                   | `undefined` | Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the `defaultChecked` prop instead.                                                                                                                                             |
| onCheckedChange | `((checked: boolean, eventDetails: Checkbox.Root.ChangeEventDetails) => void)`              | -           | Event handler called when the checkbox is ticked or unticked.                                                                                                                                                                                                    |
| indeterminate   | `boolean`                                                                                   | `false`     | Whether the checkbox is in a mixed state: neither ticked, nor unticked.                                                                                                                                                                                          |
| value           | `string`                                                                                    | -           | The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted.&#xA;When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on". |
| form            | `string`                                                                                    | -           | Identifies the form that owns the hidden input.&#xA;Useful when the checkbox is rendered outside the form.                                                                                                                                                       |
| nativeButton    | `boolean`                                                                                   | `false`     | Whether the component renders a native `<button>` element when replacing it&#xA;via the `render` prop.&#xA;Set to `true` if the rendered element is a native button.                                                                                             |
| parent          | `boolean`                                                                                   | `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  | `string`                                                                                    | -           | The value submitted with the form when the checkbox is unchecked.&#xA;By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.                                                                                               |
| disabled        | `boolean`                                                                                   | `false`     | Whether the component should ignore user interaction.                                                                                                                                                                                                            |
| readOnly        | `boolean`                                                                                   | `false`     | Whether the user should be unable to tick or untick the checkbox.                                                                                                                                                                                                |
| required        | `boolean`                                                                                   | `false`     | Whether the user must tick the checkbox before submitting a form.                                                                                                                                                                                                |
| inputRef        | `React.Ref<HTMLInputElement>`                                                               | -           | A ref to access the hidden `<input>` element.                                                                                                                                                                                                                    |
| id              | `string`                                                                                    | -           | The id of the input element.                                                                                                                                                                                                                                     |
| className       | `string \| ((state: Checkbox.Root.State) => string \| undefined)`                           | -           | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                                                                                         |
| style           | `React.CSSProperties \| ((state: Checkbox.Root.State) => React.CSSProperties \| undefined)` | -           | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                                                                                      |
| render          | `ReactElement \| ((props: HTMLProps, state: Checkbox.Root.State) => ReactElement)`          | -           | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.                                                                    |

**Root Data Attributes:**

| Attribute          | Type | 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.Props

Re-export of [Root](/react/components/checkbox.md) props.

### Root.State

```typescript
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

```typescript
type CheckboxRootChangeEventReason = 'none';
```

### Root.ChangeEventDetails

```typescript
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.

**Indicator Props:**

| Prop        | Type                                                                                             | Default | Description                                                                                                                                                                                   |
| :---------- | :----------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| className   | `string \| ((state: Checkbox.Indicator.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style       | `React.CSSProperties \| ((state: Checkbox.Indicator.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| keepMounted | `boolean`                                                                                        | `false` | Whether to keep the element in the DOM when the checkbox is not checked.                                                                                                                      |
| render      | `ReactElement \| ((props: HTMLProps, state: Checkbox.Indicator.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

**Indicator Data Attributes:**

| Attribute           | Type | 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.Props

Re-export of [Indicator](/react/components/checkbox.md) props.

### Indicator.State

```typescript
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;
};
```

## Export Groups

- `Checkbox.Root`: `Checkbox.Root`, `Checkbox.Root.State`, `Checkbox.Root.Props`, `Checkbox.Root.ChangeEventReason`, `Checkbox.Root.ChangeEventDetails`
- `Checkbox.Indicator`: `Checkbox.Indicator`, `Checkbox.Indicator.State`, `Checkbox.Indicator.Props`
- `Default`: `CheckboxRootState`, `CheckboxRootProps`, `CheckboxRootChangeEventReason`, `CheckboxRootChangeEventDetails`, `CheckboxIndicatorState`, `CheckboxIndicatorProps`

## Canonical Types

Maps `Canonical`: `Alias` — Use Canonical when its namespace is already imported; otherwise use Alias.

- `Checkbox.Root.State`: `CheckboxRootState`
- `Checkbox.Root.Props`: `CheckboxRootProps`
- `Checkbox.Root.ChangeEventReason`: `CheckboxRootChangeEventReason`
- `Checkbox.Root.ChangeEventDetails`: `CheckboxRootChangeEventDetails`
- `Checkbox.Indicator.State`: `CheckboxIndicatorState`
- `Checkbox.Indicator.Props`: `CheckboxIndicatorProps`