Switch

Visual Variants

Size Variants

Color Variants

Verify that your on/off track colors meet 3:1 non-text contrast against the background (WCAG 1.4.11) using the Contrast Checker.

Switch Properties

Critical: The onChange handler should apply the effect immediately — no "Save" button required. This is the contract of a switch. If you need deferred application, use a Checkbox instead.

Design Token Mappings

Switches touch color, spacing, border-radius, and transition tokens. For token architecture, see the Design Tokens Complete Guide.

Thumb Translation Calculation

The thumb's translateX distance on toggle = trackWidth - thumbDiameter - (2 × inset). For an md switch: 44 - 20 - 4 = 20px. This ensures the thumb lands flush against the opposite edge.

Switch States

Transition Details

The switch toggle is a composed animation with two simultaneous transitions:

1. Thumb position: transform: translateX(0) → translateX(20px) (or reverse). Duration: 150–200ms. Easing: ease-out or spring.
2. Track color: background-color transitions from gray to active color. Duration: 150ms. Timing: simultaneous with thumb movement.

Preview these transitions with the Transition Generator and fine-tune easing curves in the Animation & Easing Tool.

Accessibility — Switch

Switches map directly to the role="switch" ARIA pattern, introduced in WAI-ARIA 1.1. This role explicitly conveys the toggle semantics — something that role="checkbox" only approximates. Validate your switch colors with the Contrast Checker.

ARIA Pattern

<!-- Native implementation using checkbox with switch role -->
<label class="switch">
  <input type="checkbox"
         role="switch"
         aria-checked="true"
         id="dark-mode">
  <span class="switch-track">
    <span class="switch-thumb"></span>
  </span>
  <span class="switch-label">Dark mode</span>
</label>

<!-- Button-based implementation -->
<button role="switch"
        aria-checked="false"
        aria-label="Enable notifications"
        id="notifications-toggle">
  <span class="switch-track">
    <span class="switch-thumb"></span>
  </span>
</button>

Key points:

• Use role="switch" — it tells AT this is a toggle, not a checkbox. Screen readers announce "Dark mode, switch, on" instead of "Dark mode, checkbox, checked."
• Use aria-checked (not checked attribute alone) with role="switch" to communicate state.
• Both <input type="checkbox" role="switch"> and <button role="switch"> are valid implementations.
• The switch MUST have a label — either via <label> association, aria-label, or aria-labelledby.

WCAG Success Criteria

Switch vs. Checkbox Decision

Do

• Apply the effect immediately when the switch toggles. This is the fundamental UX contract. No "Save Changes" button should be required.
• Always include a visible label. Never present a standalone switch without text explaining what it controls.
• Use positive framing for labels: "Enable notifications" rather than "Disable notifications." Negatively-framed switches create double-negative confusion ("disable is off" = "notifications are on?").
• Place the label to the right of the switch (or left in RTL layouts). This follows the natural reading order.
• Add icons (✓/✕ or custom) inside the thumb or track to reinforce state beyond color alone, improving accessibility for colorblind users.
• Provide immediate visual feedback — the toggle animation should complete within 150–200ms. Preview in the Transition Generator.
• Show a loading state for async toggles (e.g., toggling a server-side setting). Disable the switch and show a small spinner until the request completes.
• Handle errors gracefully for async toggles — if the API call fails, revert the switch to its previous state and show an error Toast.

Don't

• Don't use a switch for form fields that require explicit submission. That's a Checkbox.
• Don't use switches for multi-option selection. Use checkboxes for multiple choices, radio buttons for single choice.
• Don't use negative labels. "Disable auto-save" with a switch creates confusion about what "on" means.
• Don't group many switches without clear sections. A settings page with 20 unlabeled switches is overwhelming. Group with headings and dividers.
• Don't change the page layout dramatically when a switch toggles. Switches should modify behavior or appearance, not restructure the UI.
• Don't use a switch for destructive actions. Toggling "Delete my account" would be terrifying. Use a Button with a confirmation Dialog.

Async Toggle Pattern

For server-side settings, the switch must handle network latency:

1. User toggles switch → Switch visually moves, shows loading spinner
2. API call succeeds → Remove spinner, switch stays in new position
3. API call fails → Revert switch to previous position, show error Toast

This "optimistic update with rollback" pattern provides instant feedback while maintaining data integrity.

Design System Implementations

Material Design 3 significantly redesigned its switch in Material 3 (Material You). The new switch uses a larger thumb that changes size when toggled: 16px when off, 24px when on. This size difference provides an additional non-color cue for state — a smart accessibility enhancement. The track also has a visible border in the off state that disappears when on. Material 3 supports icons inside the thumb (configurable for both states) and includes a "selected + pressed" state where the thumb grows even larger.

Apple Human Interface Guidelines define the switch as a pill track with a circular thumb that slides. iOS's switch is 51×31px with no label text inside the track — the state is communicated entirely through position (left/right) and color (green/gray). Apple explicitly recommends against adding text labels inside the track, arguing that the thumb position is sufficient. Apple also mandates that switches always take effect immediately — no form submission pattern.

Ant Design's Switch supports checkedChildren and unCheckedChildren — React nodes rendered inside the track when on/off (commonly "1"/"0" or icons). It also supports loading (shows a spinner inside the thumb) and integrates with Ant's form system. The size prop offers "default" and "small."

Radix UI provides a Switch primitive with Root (the track/input) and Thumb (the sliding element). It uses role="switch" and aria-checked natively, handles keyboard interaction (Space to toggle), and is completely unstyled. The separation of Root and Thumb gives full control over animation and styling.

Chakra UI's Switch is built on a checkbox internally but renders as a switch visually. It supports colorScheme for the on-state color, size (sm/md/lg), and integrates with Chakra's form control system (label, helper text, error message). It uses role="checkbox" rather than role="switch" — a pragmatic choice for broader AT compatibility, though role="switch" is now well-supported.

Headless UI (Tailwind) provides a Switch component that's fully accessible with role="switch", aria-checked, keyboard support, and a render-prop API. No styles — you build the visual entirely with Tailwind classes. It supports Switch.Group, Switch.Label, and Switch.Description for compound labeling.

Preview switch animations and easing curves in the Transition Generator and the Animation & Easing Tool.