---
title: Checkbox
description: A control that allows the user to toggle between checked and not checked.
order: 6
tags: [components]
---

import { Preview } from "$lib/components/preview";
import { Checkbox } from "areia";

# Checkbox

A control that allows the user to toggle between checked and not checked. It uses DOM primitives like native checkbox inputs, labels, fieldsets, and legends.

[Source Code](https://github.com/ilhajs/areia/blob/main/packages/areia/src/components/checkbox/index.ts)

<Preview
  code={
    'import ilha from "ilha";\nimport { Checkbox } from "areia";\n\nexport default ilha.render(() => (\n  <Checkbox label="Accept terms and conditions" />\n));'
  }
  lang="tsx"
>
  <Checkbox label="Accept terms and conditions" />
</Preview>

## Import

```ts
import { Checkbox } from "areia";
```

## Usage

<Preview
  code={
    'import ilha from "ilha";\nimport { Checkbox } from "areia";\n\nexport default ilha.render(() => (\n  <Checkbox label="Remember me" />\n));'
  }
  lang="tsx"
>
  <Checkbox label="Remember me" />
</Preview>

## Examples

### Default

Checkbox with a built-in label. The label automatically displays in a horizontal layout with the checkbox before the label.

<Preview
  code={
    'import ilha from "ilha";\nimport { Checkbox } from "areia";\n\nexport default ilha.render(() => (\n  <Checkbox label="Accept terms and conditions" />\n));'
  }
  lang="tsx"
>
  <Checkbox label="Accept terms and conditions" />
</Preview>

### Checked

<Preview
  code={
    'import ilha from "ilha";\nimport { Checkbox } from "areia";\n\nexport default ilha.render(() => (\n  <Checkbox label="Enable notifications" checked />\n));'
  }
  lang="tsx"
>
  <Checkbox label="Enable notifications" checked />
</Preview>

### Indeterminate

Used for “select all” patterns when some but not all items are selected.

<Preview
  code={
    'import ilha from "ilha";\nimport { Checkbox } from "areia";\n\nexport default ilha.render(() => (\n  <Checkbox label="Select all" indeterminate />\n));'
  }
  lang="tsx"
>
  <Checkbox label="Select all" indeterminate />
</Preview>

### Label First Layout

Use `controlFirst: false` to place the label before the checkbox.

<Preview
  code={
    'import ilha from "ilha";\nimport { Checkbox } from "areia";\n\nexport default ilha.render(() => (\n  <Checkbox label="Enable notifications" controlFirst={false} />\n));'
  }
  lang="tsx"
>
  <Checkbox label="Enable notifications" controlFirst={false} />
</Preview>

### Disabled

<Preview
  code={
    'import ilha from "ilha";\nimport { Checkbox } from "areia";\n\nexport default ilha.render(() => (\n  <Checkbox label="Disabled" disabled />\n));'
  }
  lang="tsx"
>
  <Checkbox label="Disabled" disabled />
</Preview>

### Error

The error variant provides visual styling. For error messages, use `Checkbox.Group`.

<Preview
  code={
    'import ilha from "ilha";\nimport { Checkbox } from "areia";\n\nexport default ilha.render(() => (\n  <Checkbox label="Required field" variant="error" required />\n));'
  }
  lang="tsx"
>
  <Checkbox label="Required field" variant="error" required />
</Preview>

### Without Visible Label

When a checkbox does not have visible label text, provide an accessible name with `aria-label`.

<Preview
  code={
    'import ilha from "ilha";\nimport { Checkbox } from "areia";\n\nexport default ilha.render(() => (\n  <Checkbox aria-label="Select row" />\n));'
  }
  lang="tsx"
>
  <Checkbox aria-label="Select row" />
</Preview>

### Checkbox Group

Group multiple checkboxes with a legend and description. Use `Checkbox.Group` and `Checkbox.Item`.

<Preview
  code={
    'import ilha from "ilha";\nimport { Checkbox } from "areia";\n\nexport default ilha.render(() => (\n  <Checkbox.Group\n    legend="Notification preferences"\n    description="Choose how you want to receive updates."\n  >\n    <Checkbox.Item\n      label="Email notifications"\n      value="email"\n      checked\n    />\n    <Checkbox.Item label="SMS notifications" value="sms" />\n    <Checkbox.Item label="Product updates" value="updates" />\n  </Checkbox.Group>\n));'
  }
  lang="tsx"
>
  <Checkbox.Group
    legend="Notification preferences"
    description="Choose how you want to receive updates."
  >
    <Checkbox.Item
      label="Email notifications"
      value="email"
      checked
    />
    <Checkbox.Item label="SMS notifications" value="sms" />
    <Checkbox.Item label="Product updates" value="updates" />
  </Checkbox.Group>
</Preview>

### Checkbox Group with Error

Show validation errors at the group level.

<Preview
  code={
    'import ilha from "ilha";\nimport { Checkbox } from "areia";\n\nexport default ilha.render(() => (\n  <Checkbox.Group\n    legend="Notification preferences"\n    error="Select at least one notification method."\n  >\n    <Checkbox.Item\n      label="Email notifications"\n      value="email"\n      variant="error"\n    />\n    <Checkbox.Item\n      label="SMS notifications"\n      value="sms"\n      variant="error"\n    />\n  </Checkbox.Group>\n));'
  }
  lang="tsx"
>
  <Checkbox.Group
    legend="Notification preferences"
    error="Select at least one notification method."
  >
    <Checkbox.Item
      label="Email notifications"
      value="email"
      variant="error"
    />
    <Checkbox.Item
      label="SMS notifications"
      value="sms"
      variant="error"
    />
  </Checkbox.Group>
</Preview>

### Visually Hidden Legend

Use `Checkbox.Legend` with `class: "sr-only"` to keep the legend accessible to screen readers while hiding it visually. This is useful when the group is already labeled by nearby visible text.

<Preview
  code={
    'import ilha from "ilha";\nimport { Checkbox } from "areia";\n\nexport default ilha.render(() => (\n  <div class="flex flex-col gap-3">\n    <p class="text-base font-medium text-areia-default">\n      Notification preferences\n    </p>\n    <Checkbox.Group>\n      <Checkbox.Legend\n        label="Notification preferences"\n        class="sr-only"\n      />\n      <Checkbox.Item\n        label="Email notifications"\n        value="email"\n        checked\n      />\n      <Checkbox.Item label="SMS notifications" value="sms" />\n    </Checkbox.Group>\n  </div>\n));'
  }
  lang="tsx"
>
  <div class="flex flex-col gap-3">
    <p class="text-base font-medium text-areia-default">
      Notification preferences
    </p>
    <Checkbox.Group>
      <Checkbox.Legend
        label="Notification preferences"
        class="sr-only"
      />
      <Checkbox.Item
        label="Email notifications"
        value="email"
        checked
      />
      <Checkbox.Item label="SMS notifications" value="sms" />
    </Checkbox.Group>
  </div>
</Preview>

### Custom Legend Styling

Use `Checkbox.Legend` when you need custom typography, colors, or layout instead of the `legend` string prop.

<Preview
  code={
    'import ilha from "ilha";\nimport { Checkbox } from "areia";\n\nexport default ilha.render(() => (\n  <Checkbox.Group>\n    <Checkbox.Legend\n      label="Notification preferences"\n      class="text-sm uppercase tracking-wide text-areia-subtle"\n    />\n    <Checkbox.Item\n      label="Email notifications"\n      value="email"\n      checked\n    />\n    <Checkbox.Item label="SMS notifications" value="sms" />\n  </Checkbox.Group>\n));'
  }
  lang="tsx"
>
  <Checkbox.Group>
    <Checkbox.Legend
      label="Notification preferences"
      class="text-sm uppercase tracking-wide text-areia-subtle"
    />
    <Checkbox.Item
      label="Email notifications"
      value="email"
      checked
    />
    <Checkbox.Item label="SMS notifications" value="sms" />
  </Checkbox.Group>
</Preview>

## API Reference

### Checkbox

Single checkbox component with built-in label and horizontal layout.

| Prop            | Type                   | Default     | Description                                                                          |
| --------------- | ---------------------- | ----------- | ------------------------------------------------------------------------------------ |
| `variant`       | `"default" \| "error"` | `"default"` | Visual variant.                                                                      |
| `label`         | `unknown`              | -           | Label content for the checkbox.                                                      |
| `labelTooltip`  | `string`               | -           | Tooltip text rendered as a native title on the label text.                           |
| `controlFirst`  | `boolean`              | `true`      | When true, checkbox appears before label. When false, label appears before checkbox. |
| `checked`       | `boolean`              | -           | Whether the checkbox is checked.                                                     |
| `indeterminate` | `boolean`              | -           | Whether the checkbox is in an indeterminate visual state.                            |
| `disabled`      | `boolean`              | -           | Whether the checkbox is disabled.                                                    |
| `name`          | `string`               | -           | Name for form submission.                                                            |
| `value`         | `string`               | -           | Value for form submission.                                                           |
| `required`      | `boolean`              | -           | Whether the field is required.                                                       |
| `class`         | `string`               | -           | Additional CSS classes applied to the checkbox control.                              |
| `className`     | `string`               | -           | Alias for `class`.                                                                   |

### Checkbox.Group

Wrapper for multiple checkboxes with legend, description, and error support.

| Prop            | Type        | Default | Description                                                         |
| --------------- | ----------- | ------- | ------------------------------------------------------------------- |
| `legend`        | `unknown`   | -       | Legend content for the group.                                       |
| first argument  | `unknown[]` | -       | Checkbox item markup when no group props are needed.                |
| second argument | `unknown[]` | -       | Checkbox item markup, usually `Checkbox.Item(...)` calls.           |
| `children`      | `unknown`   | -       | Inline checkbox item markup. Prefer the second argument for groups. |
| `error`         | `unknown`   | -       | Error message for the group.                                        |
| `description`   | `unknown`   | -       | Helper text for the group.                                          |
| `disabled`      | `boolean`   | -       | Whether all controls in the fieldset are disabled.                  |
| `class`         | `string`    | -       | Additional CSS classes.                                             |
| `className`     | `string`    | -       | Alias for `class`.                                                  |

### Checkbox.Legend

Composable legend sub-component for `Checkbox.Group`. Use it instead of the `legend` prop when you need custom legend styling.

| Prop        | Type      | Default | Description             |
| ----------- | --------- | ------- | ----------------------- |
| `label`     | `unknown` | -       | Legend content.         |
| `class`     | `string`  | -       | Additional CSS classes. |
| `className` | `string`  | -       | Alias for `class`.      |

### Checkbox.Item

Individual checkbox within `Checkbox.Group`. It accepts the same props as `Checkbox`, plus `value` for form submission.

## Accessibility

### Label Requirement

Single checkboxes should have a visible `label`, an `aria-label`, or an `aria-labelledby` value so assistive technologies can announce their purpose.

### Keyboard Navigation

Because this component uses native `<input type="checkbox">`, Space toggles the checkbox and Tab moves focus between controls.

### Screen Readers

`Checkbox.Group` uses semantic `<fieldset>` and `<legend>` elements for proper grouping announcements.