docs / core / switch
Switch
a labelled on/off control that takes effect immediately. flipping it changes something now, with no save button after.
intensity · recedesrsc · client
provenance
authored in usvalayer
core / primitivesintensity
recedes · safe anywhere, including dense surfacescomposition
settings rows and preference panels, one per line with a labeldescription carries the consequence when the label alone is vaguenot for choices a form submits later. that is Checkboxnever unlabelled. the thumb alone says nothing about what it togglesa11y
role="switch" named by its label · toggles with space · disabled sets aria-disabled · focus ring on the trackjest-axedependencies
@base-ui/react (Switch + Field) · class-variance-authoritylive demo · try it out
Enable push notifications for updates.
customize
labelnames the control
descriptionhelper text under the switch
sizesm for dense rows
defaultCheckedinitial on state
disableddims and blocks the pointer
usage
import { Switch } from "@usva-ui/react/primitives/switch";
<Switch
label="Notifications"
description="Enable push notifications for updates."
/>props
| prop | type | default | notes |
|---|---|---|---|
| checked | boolean | — | controlled checked state. pair with onCheckedChange. |
| defaultChecked | boolean | false | initial state when uncontrolled. |
| onCheckedChange | (checked: boolean) => void | — | fires with the next state on every toggle. |
| disabled | boolean | false | dims to 50% and blocks the pointer. disables the whole field. |
| label | ReactNode | — | the field label, wired to the control by id. |
| description | ReactNode | — | helper text under the control. |
| size | "sm" | "md" | "md" | sm for dense rows. both keep a full-height hit area. |
get it
bun add @usva-ui/reactusage
import { Switch } from "@usva-ui/react/primitives/switch";
<Switch
label="Notifications"
description="Enable push notifications for updates."
onCheckedChange={(checked) => setEnabled(checked)}
/>