# Field: Switch Group (category: toggle)

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

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

## Overview

The switch group field displays multiple toggle switches, allowing users to select multiple options. It's similar to checkbox group but with a more prominent, settings-like visual style.

## Usage

### Basic Switch Group

```tsx

const config = FormBuilder.create('settings')
  .addField('notifications', (f) =>
    f
      .type('switch-group')
      .label('Notification Settings')
      .options([
        { label: 'Email notifications', value: 'email' },
        { label: 'Push notifications', value: 'push' },
        { label: 'SMS notifications', value: 'sms' },
      ])
      .optional(),
  )
  .addStep('main', ['notifications'])
  .build();
```

### With Default Values

```tsx
.addField('privacy', (f) =>
  f.type('switch-group')
    .label('Privacy Settings')
    .options([
      { label: 'Public profile', value: 'public' },
      { label: 'Show online status', value: 'online' },
      { label: 'Allow messages', value: 'messages' },
    ])
    .value(['public', 'messages'])
    .optional()
)
```

### JSON Configuration

```json
{
  "type": "switch-group",
  "label": "Notification Settings",
  "options": [
    { "label": "Email notifications", "value": "email" },
    { "label": "Push notifications", "value": "push" },
    { "label": "SMS notifications", "value": "sms" }
  ],
  "value": ["email"],
  "schema": { "required": false }
}
```

## Props

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

## Validation

### At Least One Selection

```tsx
.addField('channels', (f) =>
  f.type('switch-group')
    .label('Communication channels')
    .options([...])
    .required('Enable at least one channel')
)
```

### Selection Range

```tsx
.addField('features', (f) =>
  f.type('switch-group')
    .label('Features')
    .options([...])
    .required()
    .itemCount(1, 3)
)
```

## Styling

### Custom Classes

```tsx
.addField('notifications', (f) =>
  f.type('switch-group')
    .label('Notifications')
    .options([...])
    .optional()
    .classNames({
      wrapper: 'bg-muted/30 p-4 rounded-lg',
      label: 'text-lg font-semibold mb-3',
      error: 'text-destructive text-sm',
    })
)
```

### Options Layout with `optionsClassName`

```json
{
  "type": "switch-group",
  "label": "Settings",
  "optionsClassName": "space-y-4",
  "options": [...]
}
```

### Responsive Layout

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

### JSON Styling

```json
{
  "type": "switch-group",
  "label": "Notifications",
  "wrapper_className": "bg-muted/30 p-4 rounded-lg",
  "label_className": "text-lg font-semibold",
  "optionsClassName": "space-y-3",
  "columns": { "default": 12, "md": 6 }
}
```

## Related Fields

- [Switch](/docs/switch) - Single toggle switch
- [Checkbox Group](/docs/checkbox-group) - Less prominent style
- [Button Checkbox](/docs/button-checkbox) - Button style

## Switch Group vs Checkbox Group

| Use Switch Group   | Use Checkbox Group |
| ------------------ | ------------------ |
| Settings pages     | Form selections    |
| Prominent toggles  | Compact lists      |
| On/off states      | Yes/no choices     |
| Immediate feedback | Submit with form   |

## Accessibility

- Uses Radix UI Switch for each option
- Proper group labeling with ARIA
- Keyboard navigation (Tab between, Space to toggle)
- Focus visible states