---
title: Checkbox
description: "A control that allows the user to toggle between checked and not checked."
---

```tsx
import * as stylex from '@stylexjs/stylex';

import { Checkbox } from '@/components/ui/checkbox';
import { space, fontSize } from '@/lib/constants.stylex';
import { colors, font } from '@/lib/tokens.stylex';

export default function CheckboxDemo() {
  return (
    <label {...stylex.props(styles.label)}>
      <Checkbox defaultChecked /> Accept terms and conditions
    </label>
  );
}

const styles = stylex.create({
  label: {
    alignItems: 'center',
    color: colors.foreground,
    display: 'flex',
    fontFamily: font.sans,
    fontSize: fontSize.sm,
    gap: space.s2,
  },
});
```

## Install

```bash
npx shadcn@latest add @madeui/checkbox
```

## Usage

```tsx
import { Checkbox } from '@/components/ui/checkbox';

<label>
  <Checkbox defaultChecked /> Accept terms
</label>
```

## Indeterminate

```tsx
import * as stylex from '@stylexjs/stylex';

import { Checkbox } from '@/components/ui/checkbox';
import { space, fontSize } from '@/lib/constants.stylex';
import { colors, font } from '@/lib/tokens.stylex';

export default function CheckboxIndeterminate() {
  return (
    <label {...stylex.props(styles.label)}>
      <Checkbox indeterminate /> Select all
    </label>
  );
}

const styles = stylex.create({
  label: {
    alignItems: 'center',
    color: colors.foreground,
    display: 'flex',
    fontFamily: font.sans,
    fontSize: fontSize.sm,
    gap: space.s2,
  },
});
```

## Description

Use `Field` with `orientation="horizontal"`, `FieldContent`, and `FieldDescription` to pair a checkbox with helper text.

```tsx
import { Checkbox } from '@/components/ui/checkbox';
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldLabel,
} from '@/components/ui/field';

export default function CheckboxDescription() {
  return (
    <Field orientation="horizontal">
      <Checkbox id="checkbox-description-newsletter" defaultChecked />
      <FieldContent>
        <FieldLabel htmlFor="checkbox-description-newsletter">
          Newsletter
        </FieldLabel>
        <FieldDescription>
          Receive occasional product updates and announcements.
        </FieldDescription>
      </FieldContent>
    </Field>
  );
}
```

## Disabled

```tsx
import * as stylex from '@stylexjs/stylex';

import { Checkbox } from '@/components/ui/checkbox';
import { space, fontSize } from '@/lib/constants.stylex';
import { colors, font } from '@/lib/tokens.stylex';

export default function CheckboxDisabled() {
  return (
    <label {...stylex.props(styles.label, styles.disabled)}>
      <Checkbox disabled defaultChecked /> Disabled
    </label>
  );
}

const styles = stylex.create({
  label: {
    alignItems: 'center',
    color: colors.foreground,
    display: 'flex',
    fontFamily: font.sans,
    fontSize: fontSize.sm,
    gap: space.s2,
  },
  disabled: {
    opacity: 0.5,
  },
});
```

## Invalid

Set `invalid` on `Field` to show validation errors — the label and error message pick up the invalid styling, and `aria-invalid` is applied to the checkbox automatically.

```tsx
import { Checkbox } from '@/components/ui/checkbox';
import { Field, FieldContent, FieldError, FieldLabel } from '@/components/ui/field';

export default function CheckboxInvalid() {
  return (
    <Field orientation="horizontal" invalid>
      <Checkbox id="checkbox-invalid-terms" />
      <FieldContent>
        <FieldLabel htmlFor="checkbox-invalid-terms">
          Accept terms and conditions
        </FieldLabel>
        <FieldError>You must accept the terms to continue.</FieldError>
      </FieldContent>
    </Field>
  );
}
```

## API reference

Built on [Base UI Checkbox](https://base-ui.com/react/components/checkbox). The tables below cover the props this library adds or changes — every other prop is forwarded to the underlying Base UI part; see the [Base UI Checkbox API reference](https://base-ui.com/react/components/checkbox#api-reference) for the full list.

### Checkbox

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | — | Controlled checked state. |
| `defaultChecked` | `boolean` | `false` |  |
| `onCheckedChange` | `(checked: boolean) => void` | — |  |
| `indeterminate` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `style` | `StyleXStyles` | — | StyleX styles merged last — always win over the component's own styles. |