# Field: Checkbox Group (category: toggle)

URL: https://docs.forms.saastro.io/docs/checkbox-group

<FieldPreview name="checkbox-group" description="Interactive demo of checkbox group field" />

## Overview

The checkbox group field allows users to select multiple options from a list. Each option is rendered as a checkbox, and the field value is an array of selected values.

## Usage

### Basic Checkbox Group

```tsx

const config = FormBuilder.create('preferences')
  .addField('interests', (f) =>
    f
      .type('checkbox-group')
      .label('Select your interests')
      .options([
        { label: 'Technology', value: 'tech' },
        { label: 'Design', value: 'design' },
        { label: 'Business', value: 'business' },
        { label: 'Marketing', value: 'marketing' },
      ])
      .required('Please select at least one interest'),
  )
  .addStep('main', ['interests'])
  .build();
```

### With Default Values

```tsx
.addField('features', (f) =>
  f.type('checkbox-group')
    .label('Select features')
    .options([
      { label: 'Dark Mode', value: 'dark-mode' },
      { label: 'Notifications', value: 'notifications' },
      { label: 'Auto-save', value: 'auto-save' },
      { label: 'Analytics', value: 'analytics' },
    ])
    .value(['dark-mode', 'auto-save'])
    .optional()
)
```

### With Min/Max Selection

```tsx
.addField('toppings', (f) =>
  f.type('checkbox-group')
    .label('Select toppings')
    .helperText('Choose 2 to 4 toppings')
    .options([
      { label: 'Pepperoni', value: 'pepperoni' },
      { label: 'Mushrooms', value: 'mushrooms' },
      { label: 'Onions', value: 'onions' },
      { label: 'Peppers', value: 'peppers' },
      { label: 'Olives', value: 'olives' },
    ])
    .required()
    .itemCount(2, 4)
)
```

### JSON Configuration

```json
{
  "type": "checkbox-group",
  "label": "Select your interests",
  "options": [
    { "label": "Technology", "value": "tech" },
    { "label": "Design", "value": "design" },
    { "label": "Business", "value": "business" }
  ],
  "value": ["tech"],
  "schema": {
    "required": true,
    "minItems": 1
  }
}
```

## Props

| Prop               | Type                                                  | Default | Description                            |
| ------------------ | ----------------------------------------------------- | ------- | -------------------------------------- |
| `type`             | `'checkbox-group'`                                    | -       | Field type (required)                  |
| `label`            | `string`                                              | -       | Group label                            |
| `helperText`       | `string`                                              | -       | Help text below field                  |
| `options`          | `Option[]`                                            | -       | Array of checkbox options              |
| `value`            | `string[]`                                            | `[]`    | Default selected values                |
| `optionsClassName` | `string`                                              | -       | CSS classes for options container grid |
| `columns`          | `Partial<Record<Breakpoint, number>>`                 | -       | Grid columns by breakpoint             |
| `disabled`         | `boolean \| function \| ConditionGroup`               | `false` | Disable all checkboxes                 |
| `hidden`           | `boolean \| function \| ConditionGroup \| Responsive` | `false` | Hide the field                         |

## Validation

### At Least One Selection

```tsx
.addField('categories', (f) =>
  f.type('checkbox-group')
    .label('Categories')
    .options([...])
    .required('Select at least one category')
)
```

### Exact Number of Selections

```tsx
.addField('top3', (f) =>
  f.type('checkbox-group')
    .label('Select your top 3')
    .options([...])
    .required()
    .itemCount(3, 3)
)
```

### Range of Selections

```tsx
.addField('skills', (f) =>
  f.type('checkbox-group')
    .label('Skills')
    .helperText('Select 2-5 skills')
    .options([...])
    .required()
    .itemCount(2, 5)
)
```

## Conditional Logic

### Show based on another field

```tsx
.addField('addons', (f) =>
  f.type('checkbox-group')
    .label('Add-ons')
    .options([...])
    .hidden((values) => values.plan === 'free')
)
```

## Styling

### Custom Classes

```tsx
.addField('interests', (f) =>
  f.type('checkbox-group')
    .label('Interests')
    .options([...])
    .required()
    .classNames({
      wrapper: 'bg-muted/30 p-4 rounded-lg',
      label: 'text-lg font-semibold mb-3',
      error: 'text-destructive text-sm mt-2',
    })
)
```

### Options Layout with `optionsClassName`

Control how checkboxes are arranged:

```tsx
// 2 columns on mobile, 3 on tablet, 4 on desktop
.addField('skills', (f) =>
  f.type('checkbox-group')
    .label('Skills')
    .options([...])
)
```

```json
{
  "type": "checkbox-group",
  "label": "Skills",
  "optionsClassName": "grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-3",
  "options": [...]
}
```

### Responsive Field Layout

```tsx
.addField('features', (f) =>
  f.type('checkbox-group')
    .label('Features')
    .options([...])
    .columns({ default: 12, md: 6 })
)
```

### JSON Styling

```json
{
  "type": "checkbox-group",
  "label": "Interests",
  "wrapper_className": "bg-muted/30 p-4 rounded-lg",
  "label_className": "text-lg font-semibold",
  "optionsClassName": "grid grid-cols-2 gap-4",
  "columns": { "default": 12, "md": 6 }
}
```

## Related Fields

- [Checkbox](/docs/checkbox) - Single boolean checkbox
- [Switch Group](/docs/switch-group) - Multiple switches
- [Button Checkbox](/docs/button-checkbox) - Checkboxes as buttons

## Accessibility

- Uses Radix UI Checkbox for each option
- Proper group labeling with ARIA
- Keyboard navigation between options
- Focus visible states
- Screen reader support