# CheckboxGroup

> A labelled set of checkboxes that share one array value.

Category: Forms · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/checkbox-group

Use CheckboxGroup when users can choose any number of options from a short list. It renders a fieldset and legend, so the group label is announced with each option, and manages the selected values as a string array. For more than about eight options, consider MultiSelect.

## Import

```tsx
import { CheckboxGroup, Checkbox } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { Checkbox, CheckboxGroup } from '@bindshq/stance-react';

export function Basic() {
  return (
    <CheckboxGroup
      label="Notify me when"
      description="Notifications are sent to your work email."
      defaultValue={['signed']}
    >
      <Checkbox value="viewed" label="A signer opens the document" />
      <Checkbox value="signed" label="A signer completes signing" />
      <Checkbox value="declined" label="A signer declines" />
      <Checkbox value="expired" label="A request expires" />
    </CheckboxGroup>
  );
}
```

### Horizontal

```tsx
import { Checkbox, CheckboxGroup } from '@bindshq/stance-react';

export function Horizontal() {
  return (
    <CheckboxGroup
      label="Show in signature"
      orientation="horizontal"
      defaultValue={['phone', 'logo']}
    >
      <Checkbox value="phone" label="Phone" />
      <Checkbox value="address" label="Address" />
      <Checkbox value="logo" label="Logo" />
      <Checkbox value="social" label="Social links" />
    </CheckboxGroup>
  );
}
```

### Validation

```tsx
import { Checkbox, CheckboxGroup } from '@bindshq/stance-react';

export function Validation() {
  return (
    <CheckboxGroup label="Deploy to" required error="Choose at least one destination">
      <Checkbox value="m365" label="Microsoft 365" />
      <Checkbox value="google" label="Google Workspace" />
    </CheckboxGroup>
  );
}
```

### Controlled

```tsx
import * as React from 'react';
import { Checkbox, CheckboxGroup } from '@bindshq/stance-react';

export function Controlled() {
  const [value, setValue] = React.useState<string[]>(['pdf']);
  return (
    <div style={{ display: 'grid', gap: 12 }}>
      <CheckboxGroup label="Export formats" value={value} onValueChange={setValue}>
        <Checkbox value="pdf" label="PDF" />
        <Checkbox value="docx" label="Word (DOCX)" />
        <Checkbox value="html" label="HTML" />
      </CheckboxGroup>
      <span style={{ fontSize: 14 }}>Selected: {value.join(', ') || 'none'}</span>
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| CheckboxGroup | `label` (required) | `ReactNode` | None | Group label, rendered as the legend. |
| CheckboxGroup | `value` | `string[]` | None | Controlled selected values. |
| CheckboxGroup | `defaultValue` | `string[]` | `[]` | Initial selected values. |
| CheckboxGroup | `onValueChange` | `(value: string[]) => void` | None | Called with the new selection. |
| CheckboxGroup | `name` | `string` | None | Form field name applied to every checkbox. |
| CheckboxGroup | `description` | `ReactNode` | None | Help text under the legend. |
| CheckboxGroup | `error` | `ReactNode` | None | Error message; marks every checkbox invalid. |
| CheckboxGroup | `required` | `boolean` | `false` | Shows a required indicator on the legend. |
| CheckboxGroup | `disabled` | `boolean` | `false` | Disables all checkboxes. |
| CheckboxGroup | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout of the options. |
| CheckboxGroup | `hideLabel` | `boolean` | `false` | Visually hide the legend. |
| CheckboxGroup | `size` | `'sm' \| 'md'` | `'md'` | Size of every checkbox. |

## Accessibility

- Uses <fieldset> and <legend>, so the group name is announced when focus enters the group.
- Description and error are linked to the fieldset; the error uses role="alert".
- Each checkbox remains a separate tab stop, matching native behaviour.

## Keyboard

| Keys | Action |
| --- | --- |
| `Tab` | Moves between checkboxes. |
| `Space` | Toggles the focused checkbox. |

## Related

- https://stanceui.com/components/checkbox
- https://stanceui.com/components/radio-group
- https://stanceui.com/components/multi-select