# React Native CheckboxGroup

> An accessible React Native CheckboxGroup for iOS, Android and the web: pick any number of options, with a select-all box that shows a mixed state, rows or a column, in a brand, iOS, Material 3 or web design.

# CheckboxGroup

A set of [checkboxes](./checkbox) for picking any number of options. Give it `options` and it draws them; `value` is the array of checked values, in the options' order. For one choice, use a [RadioGroup](./radio-group).

```tsx
import { CheckboxGroup } from 'patine-ui';
```

```tsx live
import { Box, CheckboxGroup, Text } from 'patine-ui';

const EMAILS = [
  { value: 'replies', label: 'Replies', description: 'When someone answers your comment' },
  { value: 'mentions', label: 'Mentions', description: 'When someone @mentions you' },
  { value: 'digest', label: 'Weekly digest', description: 'The best of the week, on Mondays' },
  { value: 'product', label: 'Product news', disabled: true, description: 'Managed by your workspace admin' },
];

export default function Example() {
  const [emails, setEmails] = React.useState(['replies', 'mentions']);
  return (
    <Box border radius="lg" padding="lg" gap="sm" style={{ maxWidth: 380 }}>
      <Text weight="semibold">Email me about</Text>
      <CheckboxGroup options={EMAILS} value={emails} onValueChange={setEmails} selectAllLabel="All notifications" aria-label="Email notifications" />
    </Box>
  );
}
```

## Example: export your data

An account's privacy page: pick what to include in the export. Select all checks every allowed item, the size adds up as you go, and Export stays off until something is picked.

```tsx live
import { useState } from 'react';
import { Box, Button, CheckboxGroup, Text } from 'patine-ui';

const DATA = [
  { value: 'profile', label: 'Profile', description: 'Name, email and settings · 12 KB', size: 0.01 },
  { value: 'messages', label: 'Messages', description: '18,204 messages · 48 MB', size: 48 },
  { value: 'photos', label: 'Photos and files', description: '1,310 files · 2.1 GB', size: 2150 },
  { value: 'activity', label: 'Login history', description: 'The last 90 days · 40 KB', size: 0.04 },
  { value: 'billing', label: 'Invoices', disabled: true, description: 'Ask your workspace owner', size: 0 },
];

export default function Example() {
  const [picked, setPicked] = useState<string[]>(['profile', 'messages']);
  const mb = DATA.filter((d) => picked.includes(d.value)).reduce((sum, d) => sum + d.size, 0);
  const size = mb >= 1000 ? `${(mb / 1000).toFixed(1)} GB` : mb >= 1 ? `${Math.round(mb)} MB` : 'under 1 MB';
  return (
    <Box border radius="lg" padding="lg" gap="md" style={{ width: '100%', maxWidth: 420 }}>
      <Text weight="semibold">Download your data</Text>
      <CheckboxGroup options={DATA} value={picked} onValueChange={setPicked} selectAllLabel="Everything" aria-label="Data to export" />
      <Button disabled={!picked.length}>{picked.length ? `Export · ${size}` : 'Pick something to export'}</Button>
      <Text size="sm" color="textSecondary">We email you a link when the archive is ready. It works for 7 days.</Text>
    </Box>
  );
}
```

## Select all

`selectAllLabel` adds a parent box above the options. It's checked when every enabled option is, shows a dash (`mixed`) when some are, and checks or clears them all. Disabled options keep their state.

## Accessibility

- The options are a `group`; name it with `aria-label`. Each is a `checkbox` with its `checked` and `disabled` state, named by its label and described by its description. The select-all box reads as mixed when some are checked.
- Every row is a 44pt touch target. On the web, Tab moves between boxes and Space toggles one.

## Props

Also takes `View` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `{ value, label?, description?, disabled? }[]` | — | The choices. |
| `value` | `string[]` | — | The checked values, controlled. |
| `defaultValue` | `string[]` | `[]` | The checked values when uncontrolled. |
| `onValueChange` | `(value: string[]) => void` | — | Called when the user checks or unchecks one. |
| `selectAllLabel` | `ReactNode` | — | Adds a parent box that checks or clears them all. |
| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | A column, or rows that wrap. |
| `controlPosition` | `'start' \| 'end'` | `'start'` | Which side of its label each box sits on. |
| `disabled` | `boolean` | `false` | Disables every option. |
| `theme`, `design` | | | As every component. |
