---
title: Checkbox
description: A form-friendly checkbox component with built-in validation support
---

```tsx
'use client';

import { Checkbox } from '@/ui/forms/checkboxes/Checkbox';
import { useState } from 'react';

export function CheckboxDemo() {
  const [checked, setChecked] = useState(false);
  const [error, setError] = useState('This field is required');

  return (
    <div className="space-y-4">
      <Checkbox
        name="terms"
        value="accepted"
        checked={checked}
        onChange={(_, value) => {
          setChecked(value);
          setError(value ? '' : 'This field is required');
        }}
        validationStatus={error ? 'error' : 'default'}
        errorMessage={error}
      >
        I agree to the terms and conditions
      </Checkbox>
    </div>
  );
}
```

## Installation

Using the CLI:

```bash
npx shadcn@latest add https://develop.trident-ui.pro.clubmed/r/checkbox.json
```

## Usage

```tsx showLineNumbers
import { Checkbox } from '@/docs/lib/ui/forms/checkboxes/Checkbox';
import { useState } from 'react';

export function Component() {
  const [checked, setChecked] = useState(false);

  return (
    <Checkbox
      name="name"
      value="value"
      checked={checked}
      onChange={(_, value) => setChecked(value)}
    />
  );
}
```

## With Label

```tsx showLineNumbers
import { Checkbox } from '@/docs/lib/ui/forms/checkboxes/Checkbox';
import { useState } from 'react';

export function Component() {
  const [checked, setChecked] = useState(false);

  return (
    <Checkbox name="name" value="value" checked={checked} onChange={(_, value) => setChecked(value)}>
      Checkbox label
    </Checkbox>
  );
}
```

## With Validation

```tsx showLineNumbers
import { Checkbox } from '@/docs/lib/ui/forms/checkboxes/Checkbox';
import { useState } from 'react';

export function Component() {
  const [checked, setChecked] = useState(false);
  const [error, setError] = useState('This field is required');

  return (
    <Checkbox
      name="terms"
      value="accepted"
      checked={checked}
      onChange={(_, value) => {
        setChecked(value);
        setError(value ? '' : 'This field is required');
      }}
      validationStatus={error ? 'error' : 'default'}
      errorMessage={error}
    >
      I agree to the terms and conditions
    </Checkbox>
  );
}
```

## API Reference

### Checkbox

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `id` | `string` | generated | ID of the underlying input |
| `name` | `string` | `id` | Name of the underlying input |
| `data-testid` | `string` | `undefined` | The data-testid attribute for testing |
| `children` | `ReactNode` | `undefined` | Optional label content displayed next to the checkbox |
| `checked` | `boolean` | `undefined` | Controlled checked state |
| `defaultChecked` | `boolean` | `undefined` | Uncontrolled initial checked state |
| `disabled` | `boolean` | `false` | Disables interactions |
| `value` | `string` | `undefined` | Input value |
| `onChange` | `(event: Event, value: boolean) => void` | `undefined` | Change handler receiving browser event, checked value |
| `size` | `string` | `"size-24"` | Size utility class for the checkbox box |
| `color` | `Colors` | `"black"` | Border/text color token used by the checkbox box |
| `validationStatus` | `"default" \| "error" \| "success"` | `"default"` | Validation state used for styling and error display |
| `errorMessage` | `string` | `undefined` | Error text shown when `validationStatus="error"` |
| `className` | `string` | `undefined` | Extra CSS classes |
| `tabIndex` | `number` | `0` | Input tab order |

## Examples

```tsx
'use client';

import { Checkbox } from '@/ui/forms/checkboxes/Checkbox';

export function CheckboxDisabledDemo() {
  return (
    <div className="space-y-4">
      <Checkbox name="disabled-unchecked" value="disabled" disabled>
        Disabled unchecked
      </Checkbox>
      <Checkbox name="disabled-checked" value="disabled-checked" disabled checked>
        Disabled checked
      </Checkbox>
    </div>
  );
}
```

## Notes

- **Controlled Component**: This is a fully controlled component. You must manage the `checked` state and `onChange` handler in the parent component.
- **Validation Display**: Error message appears below the checkbox when `validationStatus="error"` and `errorMessage` is provided.
- **Disabled Priority**: Disabled state takes precedence over validation states.
- **Label Rendering**: The `children` prop renders next to the checkbox in a `<label>` when provided.
- **Client Component**: This component uses React hooks and must be used in a client component (requires "use client" directive in Next.js App Router).