Skip to content
SkillCodex
Menu

Switch

Switch

A binary control that exposes a setting as on or off.

Try the component
Context, sources and actions
Sources and revision
Updated
Version
v1.0.26 · r2
Sources
5 sources
Status
Published
Read the sources

You may have searched for: turn dark mode on or offa sliding setting that applies nowenable notifications immediately

All phrasings
Save and share

Recognize

Choices and binary states

Try it

Is this an independent value, one exclusive grouped choice, or an on/off setting?

Switch

Shared trial context

A settings flow asks the user to make a choice and understand whether it is independent, exclusive, or an on/off setting.

Switch

Mission

Switch

Toggle the setting with pointer and Space, verify the state announcement, and follow the stated save behavior.

Applies every change as you type.

Preview: Off

Live result

Autosave and its preview are disabled.

Step 1 of 3

Try

Try the component. Your live result appears just above. Move on at your own pace.

Behavior and edge case
What to observe
The labeled switch exposes its current on or off state while the product makes save timing explicit.
Edge case
If persistence fails, the switch returns to its prior state and an inline status explains the failure.

What this example shows

Switch expresses one setting as on or off; Checkbox exposes an independent checked choice, and Radio group chooses one value among alternatives. Any save timing is product policy.

Which fits your need?

Switch

Turning an account setting on or off

Checkbox

Selecting any number of independent options

Which component will you use here?
Difference and sources

Switch expresses one setting as on or off; Checkbox exposes an independent checked choice, and Radio group chooses one value among alternatives. Any save timing is product policy.

Read the sources

    Parts of the specimen

    Select a numbered marker on the schematic, or use the list below, to see its role. The schematic shows the concept's representative state.

    Label

    The persistent text that names a control or field.

    Position in the atlas

    Relationship map

    Locate the chapter, neighboring concepts, and the next useful decision.

    • Chapter

      Choices and binary states

      Switch belongs to this comparison group.

    • Do not confuse

      Checkbox

      Choose Switch if a single setting is turned on or off, such as notifications or dark mode. Choose Checkbox if the user selects any number of options or agrees to a statement, such as accepting terms.

      Compare this pair
    • Do not confuse

      Radio group

      Choose Switch if the only question is whether one setting is on or off. Choose Radio group if the user picks one option among several named alternatives, such as a shipping method.

      Compare this pair
    • Next step

      Compare the concepts in the chapter before choosing an implementation.

      Open the chapter

    In your own words

    Understand

    What people describe

    Documented aliases: toggle switch, on-off switch, settings toggle

    • turn dark mode on or off
    • a sliding setting that applies now
    • enable notifications immediately
    • an on off control in settings
    • switch this feature without saving
    • a toggle that changes state right away

    Choose

    Use it when

    • Turning an account setting on or off
    • Exposing the current state of a binary setting

    Avoid it when

    • The value is an independent checked choice rather than an on or off setting
    • The choice is one of three or more mutually exclusive values

    Compare

    Compare similar concepts

    Verification checklist

    Try these actions in the lab, then check the same behaviours in your agent’s result. Adapt the example names to your interface.

    1. 1. Do this

      Turn the setting on with the pointer, then turn it off with Space while it has focus.

      Expected result

      Both methods change the same on/off state, and the setting’s label stays the same.

    2. 2. Do this

      Change the setting and follow the stated saving rule, including Save if the form requires it.

      Expected result

      The interface clearly distinguishes the chosen state from a saved change; it does not imply persistence before saving succeeds.

    3. 3. Do this

      In the test example, enable the simulated save failure and try changing the switch.

      Expected result

      The failed change is explained and the previous saved state is restored, so the switch does not claim a change that failed.

    Full contract
    1. 1The control exposes an unambiguous on or off state
    2. 2The label stays constant when the state changes
    3. 3On and off differ by more than color
    4. 4Failure restores state and is explained in context

    Understand → Recognize → Choose → Compare

    Pack for your agent

    Pre-written instructions to paste into your agent. Copying executes nothing.

    Implement correctly

    Build Switch without breaking its behavior

    # Implement Switch in your agent
    
    ## Objective
    Implement Switch for this verified behavior: A binary control that exposes a setting as on or off.
    
    ## Prerequisites
    - Inspect the repository, design system, and existing tests first.
    - Preserve unrelated changes and keep the file scope bounded.
    - Confirm that Switch matches the need before writing code.
    
    ## Required behavior
    - Activation changes the binary state; when that value is persisted is a separate product decision.
    - The control keeps the same accessible name while its checked, on, or off state changes.
    
    ## States to cover
    - Setting off
    - Setting on
    
    ## Accessibility
    - ARIA role: switch
    - The primary control or named region for Switch has a stable accessible name from visible text or an explicit programmatic label; placeholder text and tooltips are not names.
    - The switch is one visible focus stop and its label activates the same control.
    - Not applicable: the setting persists until toggled again; a failed update restores the prior state.
    - The stable accessible name and current on or off state are announced after every change.
    - Tab focuses the switch
    - Space toggles on and off
    
    ## When not to use
    - The value is an independent checked choice rather than an on or off setting
    - The choice is one of three or more mutually exclusive values
    
    ## Acceptance criteria
    - The control exposes an unambiguous on or off state
    - The label stays constant when the state changes
    - On and off differ by more than color
    - Failure restores state and is explained in context
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    
    • @radix-ui/react-switch
    • Requires · Access to the repository, design system, and tests
    Why it works
    • The need is tied to canonical behavior before any technical choice.
    • States, accessibility, and non-goals prevent a merely visual implementation.
    • Acceptance criteria and the output format make verification observable.

    Try next

    Verify Switch on a real journey

    # Verify Switch after implementation
    
    ## Objective
    Audit the Switch implementation against its behavior, states, and accessibility requirements without changing it automatically.
    
    ## Checks
    - Replay the smallest representative journey.
    - Check keyboard behavior, focus, accessible name, and announcements.
    - Tie each gap to a specific acceptance criterion.
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    

    sha256:2df20edb8bb4f1f8d3d7943bd799b5e1143ae2a7c6ce2594ddb05504f3841df3

    Diagnose a problem

    Find and fix the Switch defect

    # Debug Switch in your agent
    
    ## Observed symptom
    [DESCRIBE THE SYMPTOM HERE]
    
    ## Observable checks
    - Reproduce the issue with the smallest relevant journey.
    - Compare behavior with the documented states and transitions for Switch.
    - Verify keyboard behavior, focus, accessible name, and announcements.
    
    ## Possible causes
    - The chosen primitive does not match the expected behavior.
    - A state, transition, or focus return is missing.
    - A neighboring component captures an event or hides an accessible signal.
    
    ## Bounded corrections
    - Fix the reproduced cause without recreating neighboring components.
    - Preserve the public contract and add a focused regression test.
    - Do not install dependencies or change remote state without authorization.
    
    ## Final verification
    - The control exposes an unambiguous on or off state
    - The label stays constant when the state changes
    - On and off differ by more than color
    - Failure restores state and is explained in context
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    
    • @radix-ui/react-switch
    • Requires · Access to the repository, design system, and tests
    Why it works
    • The explicit symptom prevents starting from an assumed fix.
    • Checks separate behavior, accessibility, and neighboring interference.
    • The fix stays bounded and must produce regression evidence.

    Try next

    Lock in the Switch fix

    # Prevent the Switch regression
    
    ## Objective
    Turn the reproduced cause into a focused regression test and compare Switch with neighboring concepts before widening the fix.
    
    ## Checks
    - Prove that the test fails before the fix.
    - Prove that it passes after the bounded fix.
    - Verify that no neighboring component changed behavior.
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    

    sha256:49a3f6afd80195e26a5ae7106b6d461f52c71299d99f70e08e67390e787b4a23

    Full entry, saving and provenance

    Pre-written instruction by SkillCodex — your request is neither sent nor used to adapt this text; no content is generated, and copying executes nothing.

    Pack digest: sha256:b0908873e42adf178eb415401e32d5e2cf81bb9e6b3eb50da93c04a1877e3ddb

    In code

    TechnologyPrimitiveVersionCaveat
    @radix-ui/react-switch

    Switch.Root

    @radix-ui/react-switch@1.3.3Radix exposes on and off state; the product decides when the value is committed and still provides a visible label and feedback.

    Technical details

    Behaviors

    • Toggle a choice

      Activation changes the binary state; when that value is persisted is a separate product decision.

    • Keep a stable label

      The control keeps the same accessible name while its checked, on, or off state changes.

    States

    • Setting off

      Setting off

    • Setting on

      Setting on

    State transitions

    • Setting off → Setting on

      Pointer, touch, or Space turns the exposed setting on; persistence follows the stated product policy.

    • Setting on → Setting off

      Pointer, touch, or Space turns the exposed setting off; persistence follows the stated product policy.

    Test scenarios

    Context
    Appearance settings include a Reduce motion preference whose save behavior is stated beside the control.
    Mission
    Toggle the setting with pointer and Space, verify the state announcement, and follow the stated save behavior.
    Primary state
    The labeled switch exposes its current on or off state while the product makes save timing explicit.
    Edge case
    If persistence fails, the switch returns to its prior state and an inline status explains the failure.

    Visual signals

    • Track with a movable thumb
    • Persistent setting label
    • Distinct on and off states beyond color

    Behavioral signals

    • Activation changes the exposed on or off state
    • Space toggles the focused switch
    • State is announced as on or off

    Accessibility

    Role
    switch
    Accessible name
    The primary control or named region for Switch has a stable accessible name from visible text or an explicit programmatic label; placeholder text and tooltips are not names.
    Focus
    The switch is one visible focus stop and its label activates the same control.
    Dismissal
    Not applicable: the setting persists until toggled again; a failed update restores the prior state.
    Scroll
    Scrolling the page does not change the value. The focused control and any associated message remain visible above fixed interface regions.
    Announcement
    The stable accessible name and current on or off state are announced after every change.
    Keyboard
    • Tab focuses the switch
    • Space toggles on and off

    Bindings

    Open the HTML, ARIA, Radix, and shadcn matrix
    • Switch.Root

      implementationKind
      radix
      nativeElement
      Not applicable
      ariaPattern
      switch
      radixPrimitive
      Switch
      shadcnRecipe
      Switch
      runtimeDependency
      @radix-ui/react-switch@1.3.3
      packageName
      @radix-ui/react-switch
      exportName
      Switch.Root
      exactVersion
      1.3.3
      status
      verified
      sourceId
      source-ui-radix-switch
      deprecationStatus
      active
      replacement
      Not applicable
      validFrom
      Not applicable
      validUntil
      Not applicable

      Equivalence caveat: Radix exposes on and off state; the product decides when the value is committed and still provides a visible label and feedback.

      Verify binding source

    Sources

    • WAI-ARIA APG: Switch Pattern
      sourceId
      source-ui-aria-switch
      kind
      documentation
      canonicalUrl
      https://www.w3.org/WAI/ARIA/apg/patterns/switch/
      publisher
      W3C WAI
      sourceRevision
      http-last-modified:2026-07-09T07:07:36Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:573f87ee88fe4024f17bf6fb41bc90d8d0211f9e351d2cece22a560e36a43c4f
      status
      verified

      Claim covered: Switch: informative APG guidance for the switch pattern: roles, states, relationships, and keyboard interaction.

    • Radix Primitives: Switch
      sourceId
      source-ui-radix-switch
      kind
      documentation
      canonicalUrl
      https://www.radix-ui.com/primitives/docs/components/switch
      publisher
      Radix Primitives
      sourceRevision
      http-etag:W/"1fe969f2abd70720867b2c31e5e4d503"
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:012512f04d7167ec3d9baa3400dfc80972c1870826788b0ea3c25c7fa0c916fd
      status
      verified

      Claim covered: Switch: documented parts, state APIs, interaction behavior, and implementation limits for Radix Switch.

    • WHATWG HTML: The input element
      sourceId
      source-ui-html-input
      kind
      standard
      canonicalUrl
      https://html.spec.whatwg.org/multipage/input.html#the-input-element
      publisher
      WHATWG
      sourceRevision
      http-last-modified:2026-07-19T13:52:46Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:4699d26dbf428296b4b352b480b75c846a9a6b23cf3f124d6d6fe6b5e19d4eba
      status
      verified

      Claim covered: Switch: normative native semantics, states, attributes, and browser behavior for input.

    • WAI-ARIA APG: Checkbox Pattern
      sourceId
      source-ui-aria-checkbox
      kind
      documentation
      canonicalUrl
      https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/
      publisher
      W3C WAI
      sourceRevision
      http-last-modified:2026-07-09T07:07:36Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:d181058b11445310619a7ce2a021f27e346ce3b2112eb32787f9157dbfee011a
      status
      verified

      Claim covered: Switch: informative APG guidance for the checkbox pattern: roles, states, relationships, and keyboard interaction.

    • WCAG 2.2: Focus Appearance
      sourceId
      source-ui-wcag-understanding-focus-appearance
      kind
      documentation
      canonicalUrl
      https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html
      publisher
      W3C WAI
      sourceRevision
      http-last-modified:2026-07-02T10:07:49Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:fdcf316a1f0e3cc758eda9618322d132862124ff0a3f3b1a3acbf20daf804ff0
      status
      verified

      Claim covered: Switch: informative WCAG guidance for evaluating visible keyboard focus appearance.