Skip to content

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.

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.

Press Tab to focus the switch.

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.

The application owns checked when it is supplied and must update it in onCheckedChange.

Supply aria-label or aria-labelledby when label is omitted.

The visible label remains associated when id is supplied.

uncheckedValue includes an off switch in the submitted data. The application handles submission.

readOnly preserves the state while preventing changes. It does not apply the disabled appearance.

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.

  • Provide label, aria-label, or aria-labelledby. The visible label activates the switch.
  • Space changes a focused switch. Disabled switches cannot be changed or submitted.
  • With name, a checked switch submits value, which defaults to "on". An unchecked switch is omitted unless uncheckedValue is provided. The application owns any validation rule.
  • Keep the focus indicator visible when overriding className.
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.