# Checkbox (/docs/components/checkbox)



<ComponentPreview name="checkbox-demo" />

## Overview [#overview]

Use a checkbox when the user can turn an independent option on or off.

Checkboxes are right for preferences, permissions, optional settings, and multi-select lists. Use a radio group when the user must choose exactly one option from a set.

Use Checkbox Group when several checkboxes belong to the same question or setting. Groups are useful for permissions, filters, notification channels, roles, and feature selections where more than one option can be selected.

## Anatomy [#anatomy]

A checkbox has an input, visual indicator, label, optional description, and state. The label should make sense when read on its own.

A checkbox group provides shared state and contains individual checkbox items. It should have a group label or surrounding Fieldset so users understand what the choices are about.

## Behavior [#behavior]

A checkbox can be checked, unchecked, disabled, or invalid. Some grouped checkbox patterns also use an indeterminate parent state to show that only some child items are selected.

Use disabled items for options that are visible but unavailable. Use parent checkboxes when a group needs select-all behavior. Use nested parent checkboxes when choices are hierarchical.

## Accessibility [#accessibility]

Always connect the checkbox to a label. Descriptions and errors should be associated through Field when the checkbox appears in a form.

Group related checkboxes with a visible label. Make sure each checkbox has its own label and that parent states are understandable through text, not only the visual indeterminate mark.

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTab value="cli">
      CLI
    </TabsTab>

    <TabsTab value="manual">
      Manual
    </TabsTab>
  </TabsList>

  <TabsPanel value="cli">
    ```bash
    npx love-ui@latest add checkbox
    ```
  </TabsPanel>

  <TabsPanel value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @base-ui-components/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="checkbox" title="components/ui/checkbox.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsPanel>
</CodeTabs>

## Usage [#usage]

```tsx
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox"
```

```tsx
<Checkbox />
```

```tsx
<CheckboxGroup defaultValue={["next"]}>
  <Label>
    <Checkbox value="next" />
    Next.js
  </Label>
  <Label>
    <Checkbox value="vite" />
    Vite
  </Label>
  <Label>
    <Checkbox value="astro" />
    Astro
  </Label>
</CheckboxGroup>
```

## Examples [#examples]

The examples show disabled, described, card-style, and form-connected checkboxes.

For accessible labelling and validation, prefer using the `Field` component to wrap checkboxes. See the related example: [Checkbox field](/ui/docs/components/field#checkbox-field).

### Disabled [#disabled]

<ComponentPreview name="checkbox-disabled" />

### With Description [#with-description]

<ComponentPreview name="checkbox-with-description" />

### Card Style [#card-style]

<ComponentPreview name="checkbox-card" />

### Form Integration [#form-integration]

Field provides accessible labelling and validation primitives for form controls. Use it with `Form` to submit values.

<ComponentPreview name="checkbox-form" />

## Checkbox Group [#checkbox-group]

Checkbox Group is included in the same component file. Use it when several checkboxes answer the same question or share one submitted value.

For accessible group labelling and validation, prefer wrapping checkbox groups with `Field` and `Fieldset`. See the related example: [Checkbox group field](/ui/docs/components/field#checkbox-group-field).

### Basic Group [#basic-group]

<ComponentPreview name="checkbox-group-demo" />

### With Disabled Item [#with-disabled-item]

<ComponentPreview name="checkbox-group-disabled" />

### Parent Checkbox [#parent-checkbox]

<ComponentPreview name="checkbox-group-parent" />

### Nested Parent Checkbox [#nested-parent-checkbox]

<ComponentPreview name="checkbox-group-nested-parent" />

### Group Form Integration [#group-form-integration]

<ComponentPreview name="checkbox-group-form" />