Switch
An on and off control for a setting that takes effect at once, in two sizes.
A switch turns a setting on or off, and the change applies immediately, like a light switch: email alerts, compact rows. When the choice is submitted with a form, or needs confirmation, use a checkbox instead.
You receive an email when a payment fails.
// apps/docs/examples/ui/switch.tsx'use client';
import {useState} from 'react';
import { Field, FieldContent, FieldDescription, FieldGroup, FieldLabel,} from '@workspace/active-ui/components/primitives/field';import {Switch} from '@workspace/active-ui/components/primitives/switch';
/** * Settings that take effect at once: a switch beside its label and * description, the small size, and a disabled switch. A switch reports its * state with `role="switch"` and `aria-checked`. */export default function SwitchExample() { const [alerts, setAlerts] = useState(true); return ( <FieldGroup className="w-full max-w-md"> <Field orientation="horizontal"> <FieldContent> <FieldLabel htmlFor="switch-alerts">Email alerts</FieldLabel> <FieldDescription> {alerts ? 'You receive an email when a payment fails.' : 'You receive no emails about failed payments.'} </FieldDescription> </FieldContent> <Switch id="switch-alerts" checked={alerts} onCheckedChange={setAlerts} /> </Field> <Field orientation="horizontal"> <Switch id="switch-compact" size="sm" /> <FieldLabel htmlFor="switch-compact">Compact rows</FieldLabel> </Field> <Field orientation="horizontal" data-disabled> <Switch id="switch-sync" disabled defaultChecked /> <FieldLabel htmlFor="switch-sync"> Synchronise with the archive (managed by your administrator) </FieldLabel> </Field> </FieldGroup> );}Usage#
import { Field, FieldLabel,} from '@workspace/active-ui/components/primitives/field';import {Switch} from '@workspace/active-ui/components/primitives/switch';
<Field orientation="horizontal"> <Switch id="alerts" checked={alerts} onCheckedChange={setAlerts} /> <FieldLabel htmlFor="alerts">Email alerts</FieldLabel></Field>;States and sizes#
checkedandon(controlled) orChecked Change default.Checked size:default, orsmfor dense lists and tables.disableddims the switch and skips it with the keyboard;aria-gives it the error ring.invalid
What your application provides#
A label, and a description when the effect is not obvious from the label. Keep the label the same in both states: it names the setting, the switch shows its state.
The effect of the change, and its feedback. When the change can fail, such as a setting saved on a server, show the result and set the switch back if it failed.
Accessibility and keyboard#
SpaceandEntertoggle the focused switch.It is a
role="switch"button witharia-; a hidden checkbox carrieschecked nameandvalueinto a native form.The hit area extends beyond the visible track.
API#
Import from @workspace/
Props marked Base UI are behaviour of the Base UI part this component is built on.
Props
- Type
boolean
Whether the switch is currently active.
To render an uncontrolled switch, use the default prop instead.
- Type
boolean- Default
false
Whether the switch is initially active.
To render a controlled switch, use the checked prop instead.
- Type
boolean- Default
false
Whether the component should ignore user interaction.
- Type
string
Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form.
- Type
string
The id of the hidden input element.
When native is true, the id is applied to the root element.
- Type
string
Identifies the field when a form is submitted.
- Type
boolean- Default
false
Whether the user should be unable to activate or deactivate the switch.
- Type
boolean- Default
false
Whether the user must activate the switch before submitting a form.
- Type
"default""sm"- Default
'default'
The size of the track and thumb: default, or sm for dense lists and tables.
- Type
string
The value submitted with the form when the switch is off. By default, unchecked switches do not submit any value, matching native checkbox behavior.
- Type
string
The value submitted with the form when the switch is on. By default, switch submits the "on" value, matching native checkbox behavior.
- Type
Ref<HTMLInputElement>
A ref to access the hidden <input> element.
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Events
Called by the component when something happens.
- Type
(checked, eventDetails) => void
Event handler called when the switch is activated or deactivated.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
This page adapts the Switch documentation of shadcn/ui (MIT licence) to this package; see Third-party notices.