---
title: "Switch"
description: "A labelled on-or-off control that commits the moment it is flipped, for a single setting rather than a form value submitted later."
url: "https://opsinjs.pensievelabs.org/docs/components/switch"
source: "https://opsinjs.pensievelabs.org/docs/components/switch.md"
section: "Components"
status: "shipped"
kind: "component"
category: "actions-and-forms"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["toggle"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="switch"
  status="shipped"
  questions="[
  &#x22;No contrast pair has been measured: the card thumb against the accent fill when on, against the muted fill when off, and the hairline round both.&#x22;,
  &#x22;Nobody has listened to this switch in a screen reader, so whether role=\&#x22;switch\&#x22; with its label and helper line reads usefully is reasoned, not heard.&#x22;,
  &#x22;Forced colours, prefers-contrast: more and right-to-left layout are unhandled, and the reduced-motion thumb has been checked only in an emulated browser.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="switch" unbuilt="false" importPath="@/components/ui/switch" dependencies="[&#x22;@base-ui/react&#x22;]" />

```tsx
import { Switch } from "@/components/ui/switch"
```

```tsx
<Switch
  label="Larger text"
  checked={largerText}
  onCheckedChange={setLargerText}
/>
```

## Examples [#examples]

<ComponentPreview name="switch" />

### A setting that applies now [#a-setting-that-applies-now]

`checked` and `onCheckedChange` commit "Larger text" on the flip, not on a later
submit. No helper line, because the label alone says what the setting does.

<ComponentPreview name="switch-a-setting-that-applies-now" kind="example" align="start" />

### A setting with a helper line [#a-setting-with-a-helper-line]

`description` adds one sentence under the label saying what turning the switch on
changes. It is read as the description, so the accessible name stays the label.

<ComponentPreview name="switch-with-a-description" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;A single setting, such as a Larger text preference, that takes effect the moment it is flipped.&#x22;,
  &#x22;A binary state the product commits straight away, with nothing submitted later and the reader free to flip it back.&#x22;,
]"
  avoid="[
  { case: &#x22;The toggle would record that the reader agreed to something. Consent is a decision with a record.&#x22;, instead: &#x22;consent-sheet&#x22; },
  { case: &#x22;The value is proposed now and submitted later with a form.&#x22;, instead: &#x22;checkbox&#x22; },
]"
/>

## Accessibility [#accessibility]

The audit found nothing to change in the source.

* `role="switch"` comes from Base UI's Switch.Root, the accessible name is a visible
  label span tied by `aria-labelledby`, and state rides `aria-checked`.
* On and off are carried by thumb position and `aria-checked`, not the fill alone,
  and a `border-border` hairline survives `forced-colors: active` and a stripped fill.
* The 24px AA target floor is met by the track, and the 44pt house floor by the
  enclosing label row, which toggles the control.
* Focus sits on the track with the house ring. While the row is held the thumb
  squashes towards where it will go, and it travels on `spring-snap`. Under
  `prefers-reduced-motion: reduce` it does not squash and reaches the other side in one
  frame.
* It uses only neutral chrome and the accent fill, and `pnpm run check:a11y`
  confirms on every commit that no colour literal, `px` type size or banned word appears.

**Residual items.** No contrast pair has been read yet, so the report below stands in for
numbers nobody has produced.

<KeyboardTable
  name="switch"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves focus onto the switch&#x22;,
    notes: &#x22;A single tab stop. A disabled switch is skipped.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves focus back off the switch&#x22;,
    notes: &#x22;One stop in reverse too.&#x22;,
  },
  {
    keys: &#x22;Space&#x22;,
    action: &#x22;Flips the switch&#x22;,
    notes: &#x22;onCheckedChange fires with the new boolean.&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Flips the switch&#x22;,
    notes: &#x22;Base UI binds Enter as well as Space.&#x22;,
  },
  {
    keys: &#x22;Arrow keys&#x22;,
    action: &#x22;Nothing&#x22;,
    notes: &#x22;Nothing to move focus between.&#x22;,
  },
]"
/>

<ContrastReport component="switch" />

## Props interface [#props-interface]

<PropsTable name="SwitchProps" />

`checked` and `onCheckedChange` make this a controlled component with no internal
state. `label` is required: a missing or empty label raises a development warning.
`disabled` keeps the switch visible and labelled while refusing focus and every
key. `className` is merged onto the root row and must carry neither colour axis.

### Data attributes [#data-attributes]

<DataAttributesTable
  name="switch"
  rows="[
  {
    attribute: &#x22;data-slot&#x22;,
    condition: &#x22;On the root and every inner part&#x22;,
    value: &#x22;switch, switch-label, switch-description, switch-control, switch-thumb&#x22;,
  },
  {
    attribute: &#x22;data-checked / data-unchecked&#x22;,
    condition: &#x22;On the control and the thumb, one or the other&#x22;,
    value: &#x22;Present with no value; reflects checked&#x22;,
  },
  {
    attribute: &#x22;data-disabled&#x22;,
    condition: &#x22;On the control while disabled&#x22;,
    value: &#x22;Present with no value&#x22;,
  },
]"
/>
