Switch & Toggle
⋯
Switch renders the Figma Switch anatomy: a 44×24 px track, a 20 px thumb, and an optional label.
Figma specifies On and Off appearances. Switch renders in Light and Dark. See
Light and Dark.
Toggle remains upcoming and has no supported package import.
import { Switch } from "@nesra/ui/switch";
export function AirplaneMode() { return <Switch label="Airplane mode" name="airplane-mode" />;}Switch is also exported from @nesra/ui.
Examples
Section titled “Examples”import { Switch } from "@nesra/ui/switch";
export function SwitchOffExample() { return <Switch label="Airplane mode" />;}import { Switch } from "@nesra/ui/switch";
export function SwitchOnExample() { return <Switch label="Wi-Fi" defaultChecked />;}Disabled
Section titled “Disabled”import { Switch } from "@nesra/ui/switch";
export function SwitchDisabledExample() { return ( <div className="grid justify-items-start gap-nesra-spacing-lg"> <Switch label="Airplane mode unavailable" disabled /> <Switch label="Wi-Fi unavailable" defaultChecked disabled /> </div> );}Figma specifies On and Off, but no separate disabled appearance. A disabled switch keeps full
opacity. It uses the disabled roles that Checkbox and Radio use: the Off track is
foundation-bg-disabled, the On track is action-primary-disabled, and the thumb is
icon-disabled. The label uses text-support.
Keyboard focus
Section titled “Keyboard focus”import { Switch } from "@nesra/ui/switch";
export function SwitchFocusExample() { return ( <div className="grid justify-items-start gap-nesra-spacing-md"> <Switch label="Airplane mode" /> <p className="type-nesra-body-small-regular text-nesra-text-support"> Press Tab to focus the switch. </p> </div> );}Keyboard focus shows shadow-nesra-focus-ring-offset (Figma Box Shadow/Focus ring offset), a 2px
foundation-bg-neutral gap followed by a 2px effects-focus-ring ring. Figma has no focused Switch
variant. The library uses the ring that Figma assigns to filled controls, so the ring stays
separate from a dark On track. Pointer focus does not show it.
Controlled
Section titled “Controlled”import { Switch } from "@nesra/ui/switch";import { useState } from "react";
export function SwitchControlledExample() { const [enabled, setEnabled] = useState(false);
return <Switch label="Notifications" checked={enabled} onCheckedChange={setEnabled} />;}The application owns checked when it is supplied and must update it in onCheckedChange.
Without a visible label
Section titled “Without a visible label”import { Switch } from "@nesra/ui/switch";
export function SwitchAccessibleNameExample() { return <Switch aria-label="Enable notifications" />;}Supply aria-label or aria-labelledby when label is omitted.
Custom ID
Section titled “Custom ID”import { Switch } from "@nesra/ui/switch";
export function SwitchCustomIdExample() { return <Switch id="airplane-mode" label="Airplane mode" />;}The visible label remains associated when id is supplied.
Form values
Section titled “Form values”import { Button } from "@nesra/ui/button";import { Switch } from "@nesra/ui/switch";import { useState, type SyntheticEvent } from "react";
export function SwitchFormExample() { const [result, setResult] = useState("");
function handleSubmit(event: SyntheticEvent<HTMLFormElement>) { event.preventDefault(); const data = new FormData(event.currentTarget); setResult(`Email: ${data.get("email")}; SMS: ${data.get("sms")}`); }
return ( <form className="grid justify-items-start gap-nesra-spacing-lg" onSubmit={handleSubmit}> <Switch label="Email notifications" name="email" value="on" uncheckedValue="off" /> <Switch label="SMS notifications" name="sms" value="on" uncheckedValue="off" defaultChecked /> <Button type="submit">Save preferences</Button> {result && <output aria-live="polite">{result}</output>} </form> );}uncheckedValue includes an off switch in the submitted data. The application handles submission.
Read-only
Section titled “Read-only”import { Switch } from "@nesra/ui/switch";
export function SwitchReadOnlyExample() { return <Switch label="Managed by your organization" defaultChecked readOnly />;}readOnly preserves the state while preventing changes. It does not apply the disabled appearance.
Light and Dark
Section titled “Light and Dark”Switch uses semantic roles, so it follows the nearest .dark or data-theme="dark" ancestor with no
extra props. The enabled roles match the Figma Switch bindings.
| State | Track | Thumb | Label |
|---|---|---|---|
| Off | action-primary-disabled |
icon-static-white |
text-body |
| On | action-primary-default |
icon-on-brand |
text-body |
| Disabled, Off | foundation-bg-disabled |
icon-disabled |
text-support |
| Disabled, On | action-primary-disabled |
icon-disabled |
text-support |
The thumb has the shadow-nesra-xs shadow. In Dark, the On track is near white and the thumb is near black.
The Off thumb stays white in both modes, as Figma specifies. In Dark, both disabled tracks resolve to
the same gray, so only the thumb position shows a disabled switch’s state.
Accessibility
Section titled “Accessibility”- Provide
label,aria-label, oraria-labelledby. The visiblelabelactivates the switch. Spacechanges a focused switch. Disabled switches cannot be changed or submitted.- With
name, a checked switch submitsvalue, which defaults to"on". An unchecked switch is omitted unlessuncheckedValueis provided. The application owns any validation rule. - Keep the focus indicator visible when overriding
className.
API reference
Section titled “API reference”| Prop | Type | Default | Effect |
|---|---|---|---|
label |
ReactNode |
— | Renders a visible associated label. |
checked |
boolean |
— | Controls the on/off state. |
defaultChecked |
boolean |
false |
Initializes uncontrolled state. |
onCheckedChange |
(checked: boolean, details) => void |
— | Receives user changes. |
uncheckedValue |
string |
— | Submits a value when off if name is supplied. |
Switch forwards Base UI Switch Root props, including name, value, disabled, required,
readOnly, form, and inputRef. Its ref points to the visible switch root. inputRef points to
the hidden form input.
Styles use the semantic color roles, layout scale, and shape tokens.