# Checkbox

> A tick box with a visible label, including a mixed state.

```tsx
'use client';

import { useState } from 'react';
import { Checkbox } from '@brand-studio/ui';

const bags = ['Ethiopia Guji', 'Colombia Huila', 'Kenya Nyeri'];

export default function CheckboxDemo() {
  const [picked, setPicked] = useState(['Ethiopia Guji']);
  const toggle = (bag: string, on: boolean) => setPicked((current) => (on ? [...current, bag] : current.filter((item) => item !== bag)));
  return (
    <div style={{ display: 'grid', gap: 14, maxWidth: 360 }}>
      <Checkbox
        label="All three bags"
        checked={picked.length === bags.length}
        indeterminate={picked.length > 0 && picked.length < bags.length}
        onCheckedChange={(on) => setPicked(on ? bags : [])}
      />
      <div style={{ display: 'grid', gap: 12, paddingLeft: 32 }}>
        {bags.map((bag) => <Checkbox key={bag} label={bag} checked={picked.includes(bag)} onCheckedChange={(on) => toggle(bag, on)} />)}
      </div>
    </div>
  );
}
```

## Installation

```sh
npm install @brand-studio/ui
```

React 18 or 19 is a peer dependency. Import the stylesheet once and wrap the app in a brand theme:

```tsx
import '@brand-studio/ui/styles.css';
import { BrandTheme, Checkbox } from '@brand-studio/ui';
import brand from './brand.json';

<BrandTheme palette={brand.tokens} mode="system">
  {/* your app */}
</BrandTheme>
```

## Usage

```tsx
import { Checkbox } from '@brand-studio/ui';
```

```tsx
<Checkbox label="Grind for filter" defaultChecked />
```

## Accessibility

- Renders a native `<button role="checkbox">` with a real `<label>`. Space toggles it.
- `indeterminate` sets `aria-checked="mixed"` for a parent box whose group is partly ticked.
- `description` is linked with `aria-describedby`.

## API Reference

| Prop | Type | Default |
|---|---|---|
| `label` | `string` | – |
| `description?` | `string` | – |
| `checked?` | `boolean` | – |
| `defaultChecked?` | `boolean` | – |
| `indeterminate?` | `boolean` | – |
| `onCheckedChange?` | `((checked: boolean) => void)` | – |
| `disabled?` | `boolean` | – |
| `name?` | `string` | – |
| `value?` | `string` | – |
| `className?` | `string` | `''` |

Source: https://brandstudio.js.org/docs/components/checkbox/
