Switch
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
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add switchAlso works with shadcn:
npx shadcn@latest add @ritla/switchDependencies it brings
@base-ui/react@phosphor-icons/reactOr 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
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.
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.
Switch row: small and disabled
disabled grays out the switch and the texts.
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.
API reference
Switch
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | None | Figma's Label: name the setting, not the state. |
checked / defaultChecked | boolean | None | Figma's Value: On or Off. |
onCheckedChange | (checked: boolean) => void | None | When it's toggled. |
description | ReactNode | None | Figma's Show hint support: a helper line. |
label | ReactNode | None | Figma's Show label: a label above the row. |
size | "md" | "sm" | "md" | A 52×32 or 32×20 track. |
icon | boolean | false | Figma's Icon: a check when On, an X when Off. |
disabled | boolean | None | State = Disabled. |
name / value | string | None | For forms: the value is sent while it's On. |
SwitchRow
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | None | Figma's Title. |
description | ReactNode | None | Figma's Description. |
checked / defaultChecked / onCheckedChange | … | None | Figma'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. |
divided | boolean | false | A hairline under the row and 16px above and below, for a ruled list. |
icon / disabled / name / value | … | None | As on Switch. |
SwitchCore
| Prop | Type | Default | Description |
|---|---|---|---|
aria-label / aria-labelledby | string | None | The 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 to | Use | Why |
|---|---|---|
| Turn a setting on or off, applied at once | Switch | The position shows the current state, and pressing it changes it. |
| A settings row with a title and a description | Toggle or Switch card | Room for the explanation; the whole row is the target. |
| Opt in to something saved with a form | Checkbox | Nothing happens until the form is submitted. |
| Pick between two named options (Monthly, Yearly) | Toggle group or Radio group | Both options have names; neither is “off”. |
Switches apply at once
Accepting the terms at the end of a sign-up form.
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
- 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.
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.
| Key | Action |
|---|---|
| Space | Toggles it. |
| Enter | Toggles it too. |
ARIA
role="switch"witharia-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
numeralsthroughformatNumber. - Arabic typography
- The text is
label-16Medium, the helperlabel-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.
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space