# Checkbox Group

Shared state for a set of checkboxes, with an optional select-all parent.

Source: [checkbox-group.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/checkbox-group.tsx)

```tsx
import { Checkbox } from "@/components/ui/checkbox";
import { CheckboxGroup } from "@/components/ui/checkbox-group";
import { FieldContent, FieldDescription, FieldItem, FieldLabel } from "@/components/ui/field";

export default function CheckboxGroupBasic() {
  return (
    <CheckboxGroup defaultValue={["mentions", "replies"]} aria-label="Notify me about">
      <FieldItem>
        <Checkbox value="mentions" />
        <FieldLabel>Mentions</FieldLabel>
      </FieldItem>
      <FieldItem>
        <Checkbox value="replies" />
        <FieldLabel>Replies to my comments</FieldLabel>
      </FieldItem>
      <FieldItem>
        <Checkbox value="reactions" disabled />
        <FieldContent>
          <FieldLabel>Reactions</FieldLabel>
          <FieldDescription>Turned off by your workspace.</FieldDescription>
        </FieldContent>
      </FieldItem>
    </CheckboxGroup>
  );
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/checkbox-group
```

## Usage

```tsx
import { Checkbox } from "@/components/ui/checkbox";
import { CheckboxGroup } from "@/components/ui/checkbox-group";
import { FieldItem, FieldLabel } from "@/components/ui/field";

export function FruitPicker() {
  return (
    <CheckboxGroup defaultValue={["apple"]} aria-label="Fruit">
      <FieldItem>
        <Checkbox value="apple" />
        <FieldLabel>Apple</FieldLabel>
      </FieldItem>
      <FieldItem>
        <Checkbox value="pear" />
        <FieldLabel>Pear</FieldLabel>
      </FieldItem>
    </CheckboxGroup>
  );
}
```

Give each [Checkbox](https://ui.jarv.is/components/checkbox.md) a `value`, and pair it with its label in a `FieldItem`. The
group's value is an array of the checked ones.
Name the group with `aria-label` or `aria-labelledby`.

## Examples

### Select all

A checkbox with `parent` toggles all the others. Pass every value to `allValues` and control the
group's value.

```tsx
import * as React from "react";

import { Checkbox } from "@/components/ui/checkbox";
import { CheckboxGroup } from "@/components/ui/checkbox-group";
import { FieldItem, FieldLabel } from "@/components/ui/field";

const channels = [
  { value: "email", label: "Email" },
  { value: "push", label: "Push notifications" },
  { value: "sms", label: "Text messages" },
];

export default function CheckboxGroupSelectAll() {
  const [selected, setSelected] = React.useState<string[]>(["email"]);
  return (
    <CheckboxGroup
      aria-labelledby="all-channels-label"
      value={selected}
      onValueChange={setSelected}
      allValues={channels.map((channel) => channel.value)}
    >
      <FieldItem>
        <Checkbox parent />
        <FieldLabel id="all-channels-label">All channels</FieldLabel>
      </FieldItem>
      {channels.map((channel) => (
        <FieldItem key={channel.value} className="pl-6">
          <Checkbox value={channel.value} />
          <FieldLabel>{channel.label}</FieldLabel>
        </FieldItem>
      ))}
    </CheckboxGroup>
  );
}
```

## Props

| Part | Extends |
| --- | --- |
| `CheckboxGroup` | [`CheckboxGroup`](https://base-ui.com/react/components/checkbox-group#api-reference) |

The tables leave out `className`, `style` and `render`. Parts built on Base UI take them as its [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides describe.

### CheckboxGroup

| Prop             | Type                                                                         | Description                                                                                                                                |
| ---------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `value?`         | `string[]`                                                                   | Names of the checkboxes in the group that should be ticked. To render an uncontrolled checkbox group, use the `defaultValue` prop instead. |
| `defaultValue?`  | `string[]`                                                                   | Names of the checkboxes in the group that should be initially ticked. To render a controlled checkbox group, use the `value` prop instead. |
| `onValueChange?` | `((value: string[], eventDetails: CheckboxGroupChangeEventDetails) => void)` | Event handler called when a checkbox in the group is ticked or unticked. Provides the new value as an argument.                            |
| `allValues?`     | `string[]`                                                                   | Names of all checkboxes in the group. Use this when creating a parent checkbox.                                                            |
| `disabled?`      | `boolean`                                                                    | Whether the component should ignore user interaction. Default: `false`                                                                     |