Toggle Switch — Input Controls

Minimal Example

{
  "id": "notifications-enabled",
  "type": "switch",
  "label": "Email Notifications",
  "defaultValue": true,
  "width": "full",
  "binding": {
    "source": "$json",
    "path": "preferences.emailNotifications"
  }
}

Settings Reference

Setting	Type	Default	Description
`labelOn`	string	`"On"`	Label shown when the switch is toggled on
`labelOff`	string	`"Off"`	Label shown when the switch is toggled off
`size`	`sm` \| `md` \| `lg`	`md`	Switch track and knob size
`labelPosition`	`right` \| `left` \| `top`	`right`	Position of the field label relative to the switch
`showStateLabel`	boolean	true	Show the `labelOn`/`labelOff` text beside the switch knob
`checkedValue`	any	`true`	Value stored when switched on
`uncheckedValue`	any	`false`	Value stored when switched off
`color`	string (CSS)	accent color	Track color when switched on

On/Off Labels

Contextual labels communicate the state clearly. Use domain-specific language instead of generic "On/Off":

{
  "id": "two-factor-auth",
  "type": "switch",
  "label": "Two-Factor Authentication",
  "settings": {
    "labelOn": "Enabled",
    "labelOff": "Disabled",
    "size": "md"
  },
  "defaultValue": false,
  "binding": {
    "source": "$json",
    "path": "security.twoFactorEnabled"
  }
}

// Display when off:  [○    ] Disabled
// Display when on:   [    ●] Enabled

Size Variants

Size	Track Width	Use Case
`sm`	32px	Compact settings lists, table row toggles
`md`	44px	Standard form controls (default)
`lg`	56px	Prominent on/off controls, mobile-first forms

Settings Panel Pattern

A common use case is a notifications/preferences section with multiple switches:

// Section: Notification Preferences
{
  "id": "notify-email",
  "type": "switch",
  "label": "Email Notifications",
  "settings": { "labelOn": "Enabled", "labelOff": "Disabled" },
  "defaultValue": true,
  "width": "full",
  "order": 1,
  "binding": { "source": "$json", "path": "prefs.notifyEmail" }
},
{
  "id": "notify-sms",
  "type": "switch",
  "label": "SMS Notifications",
  "settings": { "labelOn": "Enabled", "labelOff": "Disabled" },
  "defaultValue": false,
  "width": "full",
  "order": 2,
  "binding": { "source": "$json", "path": "prefs.notifySms" }
},
{
  "id": "notify-push",
  "type": "switch",
  "label": "Push Notifications",
  "settings": { "labelOn": "Enabled", "labelOff": "Disabled" },
  "defaultValue": true,
  "width": "full",
  "order": 3,
  "binding": { "source": "$json", "path": "prefs.notifyPush" }
}

Custom Stored Values

Like checkbox, switch can store non-boolean values for compatibility with legacy APIs:

{
  "id": "visibility",
  "type": "switch",
  "label": "Public Profile",
  "settings": {
    "labelOn": "Public",
    "labelOff": "Private",
    "checkedValue": "public",
    "uncheckedValue": "private"
  },
  "binding": {
    "source": "$json",
    "path": "profile.visibility"
  }
}

// Stored: "public" when on, "private" when off

Conditional Field Reveal

A common pattern: toggling a switch reveals additional configuration fields. Use visibilityRule on dependent controls:

{
  "id": "custom-domain-enabled",
  "type": "switch",
  "label": "Custom Domain",
  "defaultValue": false,
  "order": 1
},
{
  "id": "custom-domain-name",
  "type": "text",
  "label": "Domain Name",
  "placeholder": "docs.yourcompany.com",
  "order": 2,
  "visibilityRule": "values['custom-domain-enabled'] === true",
  "validation": {
    "required": true,
    "pattern": "^[a-z0-9\\-\\.]+$"
  }
}

Switch vs Checkbox

Use switch when	Use checkbox when
The toggle is in a settings/preferences context	The field represents agreement or acknowledgment
The change feels immediate (enable/disable)	The value is submitted as part of a form
Mobile-first UI that benefits from large tap target	Part of a group of checkboxes (checklist)

← Radio Group Next: JSON Editor →