# Switch (/ui/components/react/switch)
```
`Switch` renders only the toggle — it has no text of its own. Wrap it and its label in a single `` so clicking either flips the switch and assistive tech announces them together; no `id`/`htmlFor` wiring needed. Use it uncontrolled with `defaultChecked`, or controlled with `checked` + `onCheckedChange`.
Reach for a switch when the change takes effect immediately (a setting that's on or off). For a value submitted later with a form — accepting terms, picking items — use a [`Checkbox`](/ui/components/react/checkbox) instead. The thumb slide and check animation are skipped when the user prefers reduced motion.
## Examples [#examples]
### Sizes [#sizes]
`size` scales the track and thumb together — `sm`, `md` (default), or `lg`.
```tsx
import { Switch } from '@appica/ui-react/switch'
export default function SwitchSizes() {
return (
)
}
```
### States [#states]
A switch is off or on, and either state can also be `disabled`. Bridging `aria-invalid` paints the error state — useful for a required toggle that hasn't been accepted.
```tsx
import { Switch } from '@appica/ui-react/switch'
export default function SwitchStates() {
return (
)
}
```
### With a label and description [#with-a-label-and-description]
A typical settings row: a title and supporting text beside the toggle. Keeping it all inside one `` makes the whole row a single target.
```tsx
import { Switch } from '@appica/ui-react/switch'
export default function SwitchWithLabel() {
return (
Marketing emails
Receive tips, product updates, and occasional offers.
)
}
```
### Controlled [#controlled]
Drive the state yourself with `checked` + `onCheckedChange` to react to every toggle.
```tsx
'use client'
import { useState } from 'react'
import { Switch } from '@appica/ui-react/switch'
export default function SwitchControlled() {
const [checked, setChecked] = useState(true)
return (
)
}
```
## RTL [#rtl]
Every Appica UI component supports right-to-left layouts out of the box. Set the `dir` attribute on a container (commonly your `` element) so CSS logical properties resolve correctly, and wrap your tree in `DirectionProvider` so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.
```tsx
import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'
export default function RootLayout({ children }) {
return (
{children}
)
}
```
The thumb slides toward the start edge instead of the end, following the resolved direction. For setup details and caveats, see the [RTL guide](/ui/docs/react/rtl).
` attributes) straight through. It exposes `data-*` state attributes (`data-checked`, `data-unchecked`, `data-disabled`, `data-readonly`, `data-invalid`, …) for styling — see the Base UI docs for the full surface.
| Prop | Type | Default | Description |
| ----------------- | ------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| `size` | 'sm' \| 'md' \| 'lg' | `'md'` | Scales the track and thumb together. |
| `checked` | `boolean` | — | Controlled on/off state. Pair with `onCheckedChange`. |
| `defaultChecked` | `boolean` | `false` | Uncontrolled initial state. |
| `onCheckedChange` | (checked: boolean, details) => void | — | Fires when the switch is flipped on or off. |
| `name` | `string` | — | Field name submitted with a form. |
| `value` | `string` | — | Value submitted with the form when the switch is on. |
| `uncheckedValue` | `string` | — | Value submitted with the form when the switch is off. |
| `form` | `string` | — | `id` of the form that owns the hidden input, when it isn't a descendant. |
| `disabled` | `boolean` | `false` | Removes the switch from the tab order and ignores interaction. |
| `readOnly` | `boolean` | `false` | Focusable but not toggleable. |
| `required` | `boolean` | `false` | Must be on before its form submits. |
| `aria-invalid` | boolean \| 'true' \| 'false' | — | Marks the error state; mirrored to `data-invalid` for styling. |
| `nativeButton` | `boolean` | `false` | Whether the element passed to `render` is a native ``. |
| `inputRef` | Ref\ | — | Ref to the hidden `ReactElement \| ((props, state) => ReactElement) | — | Replace the rendered element, or compose it with another component. |
| `className` | string \| ((state) => string) | — | Extra classes on the track, merged via `tailwind-merge`. May be a function of state. |
| `style` | CSSProperties \| ((state) => CSSProperties) | — | Inline styles, optionally derived from state. |
## Accessibility [#accessibility]
* Renders with `role="switch"`. **Space** (or **Enter**) toggles it; **Tab** moves focus to and from it.
* A switch needs an accessible name — wrap it in a `` together with its text (as shown above), or give it an `aria-label`.
* `disabled` removes the switch from the tab order and exposes `data-disabled` for styling; `readOnly` keeps it focusable but inert.
* `aria-invalid` is bridged to `data-invalid` so the error state can be styled without a wrapping `Field`.
* The thumb slide and check animation honour `prefers-reduced-motion`.