Switch

Patterns

Immediate Settings Toggle

When to use:

• One preference or feature should turn on or off directly.

Composition notes:

• Keep the visible label state-oriented.
• Give SwitchInput a name if the setting also lives in a native form.

Trade-offs:

• Strong binary affordance.
• Weak fit for groups of mutually exclusive options.

import { useState } from 'react';
import { Label, Switch, SwitchIndicator, SwitchInput, Text } from '@vega-ui/react';

export default function ParentOwnedSwitchState() {
  const [maintenance, setMaintenance] = useState(false);

  return (
    <div style={{ display: 'grid', gap: 'var(--spacing-6)', width: '100%', maxWidth: 420 }}>
      <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: 'var(--spacing-8)' }}>
        <Label htmlFor='maintenance-mode'>Maintenance mode</Label>
        <Switch>
          <SwitchInput

Settings Row With Helper Text

When to use:

• A settings screen needs a compact toggle plus short explanatory copy.

Composition notes:

• Keep the switch and primary label on one row.
• Put optional helper text below instead of inside the label itself.

Trade-offs:

• Easy to scan in preferences panels.
• Can become noisy if every row adds too much helper copy.

import { Label, Switch, SwitchIndicator, SwitchInput, Text } from '@vega-ui/react';

const settings = [
  { id: 'auto-updates', title: 'Automatic updates', description: 'Install security patches overnight.', checked: true },
  { id: 'usage-data', title: 'Share usage data', description: 'Help us improve with anonymous diagnostics.', checked: false },
  { id: 'beta-features', title: 'Beta features', description: 'Try new tools before they are released.', checked: false },
];

export default function SettingsToggle() {
  return (
    <div style={{ display: 'grid', gap: 'var(--spacing-8)', width: '100%' }}>
      {settings.map((setting) => (

Overlay Toggle List

When to use:

• A drawer or sheet contains a short list of binary settings.

Composition notes:

• Keep the list short and clearly state-oriented.
• Avoid mixing toggles with mutually exclusive choice patterns in the same visual cluster.

Trade-offs:

• Works well for compact preference panels.
• Harder to scan if too many switches are stacked with weak labels.

import { CSSProperties } from 'react';
import {
  Button,
  Heading,
  Icon,
  IconButton,
  Label,
  Sheet,
  SheetClose,
  SheetContent,
  SheetHandle,
  SheetTrigger,

Comparison

Quick Decision Rule

Use Switch for one immediate binary setting.

Switch vs Checkbox

Use Switch when:

• the control represents one immediate on/off setting

Use Checkbox when:

• the control represents an independent selectable option in a form or list

Main trade-off: switches read as immediate state changes, while checkboxes read as selection.

Switch vs Radio

Use Switch when:

• only one binary setting is involved

Use Radio when:

• the user must choose one option from a set

Main trade-off: switches toggle one setting; radios compare alternatives.

Switch vs SegmentedControl

Use Switch when:

• the choice is binary and immediate

Use SegmentedControl when:

• several always-visible exclusive options should be compared side by side

Main trade-off: switch is a binary toggle; segmented control is an exclusive option selector.

Switch vs CheckboxCard

Use Switch when:

• one binary feature should turn on or off immediately

Use CheckboxCard when:

• multiple rich options can be selected independently and the UI should read as option tiles

Choose This Component When

• The feature is one immediate binary setting.
• The label describes a feature that is on or off.
• The UI should read as a toggle, not a form choice group.
• users should not have to compare several visible alternatives first

Do Not Choose This Component When

• The user is choosing one option from several.
• Multiple independent options appear in a list.
• The state should feel like a deferred form choice instead of an immediate setting.

Troubleshooting

Switch Looks Right But Does Not Submit

Symptom

The toggle changes visually, but the value never appears in native form submission.

Likely Cause

SwitchInput was omitted.

How To Verify

• Inspect the rendered markup.
• Submit the form and check whether the switch value is present.

Fix

• Render SwitchInput inside the switch root.

Label Reads Like An Action Instead Of A State

Symptom

Users cannot tell whether the switch controls a feature state or an action.

Likely Cause

The visible text was written as "Turn on" or "Enable now" instead of naming the setting.

How To Verify

• Read the label without seeing the current checked state.
• Check whether the feature meaning is still obvious.

Fix

• Rewrite the label to describe the controlled setting, such as "Incident alerts".

Switch Was Used For The Wrong Product Model

Symptom

The UI technically works, but it feels wrong because the choice is really exclusive or multi-select.

Likely Cause

Switch was chosen for a selection model better served by Radio, Checkbox, or SegmentedControl.

How To Verify

• Check whether the setting is binary, exclusive, or independently selectable.
• Compare the surrounding flow with the intended choice model.

Fix

• Use Radio for exclusive choice sets.
• Use Checkbox for independent selectable options.
• Use SegmentedControl for always-visible exclusive options.