Skip to content

Switch

Get Ritla UI

Turns a single setting on or off, and the change applies immediately. The knob sits at the inline start when Off and moves to the inline end when On.

Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned

Open in Figma

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

PreviewCode
EnglishMirroredArabic
LTR →

Installation

  1. Add the component

    npx ritla add switch

    Also works with shadcn: npx shadcn@latest add @ritla/switch

  2. Dependencies it brings

    @base-ui/react@phosphor-icons/react

  3. Or copy by hand

    Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.

Usage

switch.tsx
import { Switch } from "@/components/ui/switch";<Switch name="alerts" defaultChecked description="Notify me when a price moves 5%">  Price alerts</Switch>

Examples

States, size and icon

icon puts a check or an X in the knob, size="sm" is the small switch, disabled disables it, and label adds a label above the row and makes it a named group.

EnglishMirroredArabic
LTR →

Switch row

SwitchRow is a switch with a title and a description for settings rows, full width: a body-16 title over body-14, 12px from the switch; size="sm" is body-14 over body-12, 8px. Figma called it "Toggle"; the button that stays pressed is Toggle.

EnglishMirroredArabic
LTR →

Switch row: small and disabled

disabled grays out the switch and the texts.

EnglishMirroredArabic
LTR →

A settings list with dividers

placement="end" puts the text at the start and the switch at the end; divided adds a hairline under each row and 16px above and below. In Arabic the switches line up on the left, and On moves the knob toward the end, to the left.

EnglishMirroredArabic
LTR →

API reference

Switch

PropTypeDefaultDescription
childrenReactNodeNoneFigma's Label: name the setting, not the state.
checked / defaultCheckedbooleanNoneFigma's Value: On or Off.
onCheckedChange(checked: boolean) => voidNoneWhen it's toggled.
descriptionReactNodeNoneFigma's Show hint support: a helper line.
labelReactNodeNoneFigma's Show label: a label above the row.
size"md" | "sm""md"A 52×32 or 32×20 track.
iconbooleanfalseFigma's Icon: a check when On, an X when Off.
disabledbooleanNoneState = Disabled.
name / valuestringNoneFor forms: the value is sent while it's On.

SwitchRow

PropTypeDefaultDescription
childrenReactNodeNoneFigma's Title.
descriptionReactNodeNoneFigma's Description.
checked / defaultChecked / onCheckedChange…NoneFigma's Value, as on Switch.
size"md" | "sm""md"Figma's Size.
placement"start" | "end""start"Where the switch sits: before the text (start) or at the row's end (end) for settings lists.
dividedbooleanfalseA hairline under the row and 16px above and below, for a ruled list.
icon / disabled / name / value…NoneAs on Switch.

SwitchCore

PropTypeDefaultDescription
aria-label / aria-labelledbystringNoneThe track and knob alone, for custom rows; name it.

Usage guidelines

A switch turns a setting on or off right away. When to pick it over a checkbox, how to name it, what happens when the change takes time or fails, and the checks before handoff.

1. Switch or checkbox

Use a switch when flipping it changes something right away: notifications, a privacy setting, dark mode. If the choice waits for a Save or Submit button, it is a checkbox. Two named opposites (Monthly or Yearly) are a choice between options, not on and off.

You need toUseWhy
Turn a setting on or off, applied at onceSwitchThe position shows the current state, and pressing it changes it.
A settings row with a title and a descriptionToggle or Switch cardRoom for the explanation; the whole row is the target.
Opt in to something saved with a formCheckboxNothing happens until the form is submitted.
Pick between two named options (Monthly, Yearly)Toggle group or Radio groupBoth options have names; neither is “off”.

Switches apply at once

Accepting the terms at the end of a sign-up form.

Do: A checkbox in a formNothing happens until Create account is pressed.
Don't: A switch in a formA switch promises an immediate change, but nothing happens until the button.

2. Label the setting, not the state

The label names what the switch controls; the switch itself shows whether it is on. Words like On, Off or Enable in the label either repeat the switch or contradict it after a press.

Name what it controls

A notification setting.

Do: The setting's name“Price alerts” stays true whether the switch is on or off.
Don't: The state in the labelAfter a press, “Alerts on” sits next to a switch that is off.

Do

  • Name the setting: Price alerts, Two-step verification.
  • Add a helper line when the effect isn't obvious.
  • Keep labels short enough to fit on one line on mobile.

Don't

  • Write the state in the label: “Notifications on”.
  • Start with a verb that flips meaning: “Disable alerts”.
  • Put a question in the label: “Get alerts?”.

3. When the change takes time or fails

Most switches apply instantly. When the change goes to a server, flip the switch right away and roll it back if the request fails, with a message that says so. When turning something off has consequences (two-step verification, sharing), ask for confirmation first and only then change the switch.

Do

  • Flip immediately; roll back and explain if the change fails.
  • Confirm changes that reduce security or delete data before switching.
  • Keep the switch usable while it saves; don't disable it without a reason.

Don't

  • Leave the switch on after the change failed.
  • Add a Save button to a screen of switches.
  • Show a spinner in place of the switch for fast changes.

4. Settings lists

In a list of settings, each row is a Toggle or a Switch card: title, an optional description, and the switch at the inline end. The whole row toggles it. Group related rows under section headers, and keep the switches in one column so their states read at a glance.

Do

  • Put the switch at the inline end of each row, in one column.
  • Let the whole row toggle the switch.
  • Explain what a setting does in the description when the title can't.

Don't

  • Mix switches and checkboxes in one settings list.
  • Put the switch right after the text, so the column zigzags.
  • Nest links or buttons inside a switch row.

5. Arabic and RTL

Off keeps the knob at the inline start; On moves it to the inline end. In Arabic that means On is the knob on the left. The RTL variant does this for you, and in code the switch follows the page direction. Don't flip it by hand, and don't mirror the check and X icons inside the knob.

On moves toward the inline end

Price alerts turned on, in Arabic.

Do: RTL variant, OnThe knob has moved toward the end of the Arabic line, the left: clearly on.
Don't: English variant in ArabicThe knob sits on the right, where an Arabic reader expects Off, though the setting is on.

Before handoff

  • Every switch applies at once; form choices are checkboxes.
  • Labels name the setting, not the state.
  • Failure and confirmation behavior is noted for risky settings.
  • Arabic screens use RTL variants, with switches at the inline end.

Accessibility

Keyboard

Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.

KeyAction
SpaceToggles it.
EnterToggles it too.

ARIA

  • role="switch" with aria-checked, named by the row's text and linked to its helper line; clicking the text toggles it.
  • The touch target is at least 48px, even at size sm.
  • Inside a form with a Submit button, use a Checkbox.

Do

  • A visible label on every switch.
  • Space toggles, and the whole row is clickable.
  • Show the state by position, not only color; the Icon option adds a check and an X.
  • Keep the knob visible when Off, at 3:1 contrast.

Don't

  • A switch with no label, or with only an icon.
  • Change other settings on the page as a side effect without announcing it.

Arabic and RTL notes

Mirrors

  • The switch sits at the start of the row (the right).
  • On moves the knob to the inline end: to the left in Arabic. Don't flip it by hand.

Does not mirror

  • The check and the X in the knob don't mirror.
Numerals
Numbers in the text follow numerals through formatNumber.
Arabic typography
The text is label-16 Medium, the helper label-12; the row grows with the taller Arabic line height.

Do

  • The RTL variant: when On, the knob is on the left.
  • The switch at the inline end of Arabic rows, the left.
  • Keep the check and X icons in the knob as they are.

Don't

  • The English variant in an Arabic row, where On looks Off.
  • Swap Off and On by hand to “fix” the direction.

Checks it passes

The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.

  • R050Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
  • R051letter-spacing applied to Arabic text (breaks the connected script)
  • R042Clipped text: content wider than its box with overflow hidden and no ellipsis
  • R043Fixed-pixel-width container whose Arabic text exceeds the space