# Field: Switch (category: toggle)

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

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

## Overview

The switch field is a toggle control for boolean values. It's more visually prominent than a checkbox and is commonly used for settings, preferences, and on/off states.

## Usage

### Basic Switch

```tsx

const config = FormBuilder.create('settings')
  .addField('notifications', (f) =>
    f
      .type('switch')
      .label('Enable notifications')
      .helperText('Receive push notifications')
      .optional(),
  )
  .addStep('main', ['notifications'])
  .build();
```

### Default On

```tsx
.addField('darkMode', (f) =>
  f.type('switch')
    .label('Dark Mode')
    .value(true)
    .optional()
)
```

### With Description

```tsx
.addField('analytics', (f) =>
  f.type('switch')
    .label('Analytics')
    .helperText('Help us improve by sending anonymous usage data. We never collect personal information.')
    .optional()
)
```

### JSON Configuration

```json
{
  "type": "switch",
  "label": "Enable notifications",
  "helperText": "Receive push notifications",
  "value": false,
  "schema": { "required": false }
}
```

## Props

| Prop         | Type                                                  | Default | Description                |
| ------------ | ----------------------------------------------------- | ------- | -------------------------- |
| `type`       | `'switch'`                                            | -       | Field type (required)      |
| `label`      | `string`                                              | -       | Label shown next to switch |
| `helperText` | `string`                                              | -       | Description text           |
| `value`      | `boolean`                                             | `false` | Initial value              |
| `size`       | `'sm' \| 'md' \| 'lg'`                                | `'md'`  | Switch size variant        |
| `columns`    | `Partial<Record<Breakpoint, number>>`                 | -       | Grid columns by breakpoint |
| `disabled`   | `boolean \| function \| ConditionGroup`               | `false` | Disable the switch         |
| `hidden`     | `boolean \| function \| ConditionGroup \| Responsive` | `false` | Hide the field             |

## Validation

### Optional (default)

```tsx
.addField('marketing', (f) =>
  f.type('switch')
    .label('Marketing emails')
    .optional()
)
```

### Required to be On

```tsx
.addField('consent', (f) =>
  f.type('switch')
    .label('I consent to data processing')
    .required()
    .mustBeTrue('You must consent to continue')
)
```

## Conditional Logic

### Show switch based on another field

```tsx
.addField('advancedSettings', (f) =>
  f.type('switch')
    .label('Show advanced options')
    .hidden((values) => !values.isPowerUser)
)
```

### Disable based on condition

```tsx
.addField('autoSave', (f) =>
  f.type('switch')
    .label('Auto-save')
    .disabled((values) => values.offlineMode === true)
)
```

## Styling

### Custom Classes

```tsx
.addField('notifications', (f) =>
  f.type('switch')
    .label('Enable notifications')
    .optional()
    .classNames({
      wrapper: 'flex items-center justify-between p-4 border rounded-lg',
      input: 'data-[state=checked]:bg-primary',
      label: 'font-medium',
      helper: 'text-muted-foreground text-sm',
    })
)
```

### Responsive Layout

```tsx
.addField('darkMode', (f) =>
  f.type('switch')
    .label('Dark Mode')
    .optional()
    .columns({ default: 12, md: 6 })
)
```

### JSON Styling

```json
{
  "type": "switch",
  "label": "Enable notifications",
  "wrapper_className": "flex items-center justify-between p-4 border rounded-lg",
  "label_className": "font-medium",
  "columns": { "default": 12, "md": 6 }
}
```

## Related Fields

- [Checkbox](/docs/checkbox) - Less prominent toggle
- [Switch Group](/docs/switch-group) - Multiple related switches
- [Radio](/docs/radio) - Single selection from options

## Switch vs Checkbox

| Use Switch           | Use Checkbox         |
| -------------------- | -------------------- |
| Settings/preferences | Forms and agreements |
| Immediate effect     | Submit with form     |
| On/off states        | Yes/no questions     |
| More prominent       | Less prominent       |

## Accessibility

- Uses Radix UI Switch for accessibility
- Supports keyboard activation (Space)
- Proper labeling via `label` prop
- Focus visible states
- Screen reader announcements for state changes