Switch
A binary toggle input rendered as a native checkbox styled to look like a sliding switch, with an optional label row.
Overview
Switch wraps a native <input type="checkbox"> with a custom CSS design. Because it is a real checkbox, it participates in forms, supports keyboard navigation natively, and works with standard React state patterns.
Two implementation notes worth knowing:
classNameapplies directly to the<input>element, not a wrapper div — be precise with your overrides.readOnlyusespointer-events-none+aria-readonly, because the HTMLreadonlyattribute does not stop a checkbox from toggling.
Import
import { Switch } from '@unflowio/ui/components/Switch';Props
| Prop | Type | Default | Description |
|---|---|---|---|
checked | boolean | — | Controlled checked state |
onChange | ChangeEventHandler<HTMLInputElement> | — | Change handler |
disabled | boolean | false | Disables interaction, sets aria-disabled and HTML disabled |
readOnly | boolean | false | Prevents interaction via pointer-events-none and sets aria-readonly |
readonly | boolean | — | Deprecated. Use readOnly |
defaultChecked | boolean | — | Uncontrolled initial value |
label | ReactNode | — | Text beside the control. Renders a label row whose whole area toggles the switch |
description | ReactNode | — | Secondary text under the label, announced as the accessible description. Needs label |
labelPlacement | 'start' | 'end' | 'end' | Where the text sits. start puts the switch at the end of a full-width row |
slotProps.row | BaseHTMLProps<HTMLLabelElement> | — | Props for the label row. Only rendered with label |
slotProps.label | BaseHTMLProps<HTMLSpanElement> | — | Props for the label text |
slotProps.description | BaseHTMLProps<HTMLSpanElement> | — | Props for the description text |
All standard HTMLInputElement props are forwarded. Provide label or aria-label.
States
<Switch checked={false} onChange={setChecked} aria-label="Toggle feature" />
<Switch checked={true} onChange={setChecked} aria-label="Toggle feature" />
<Switch checked={false} disabled aria-label="Disabled off" />
<Switch checked={true} disabled aria-label="Disabled on" />
<Switch checked={true} readOnly aria-label="Read-only on" />With a label
label renders the switch in a label row; clicking anywhere on the row toggles it. Add description for secondary text, and set labelPlacement="start" for settings lists where the switch sits at the end of the row. A read-only switch ignores clicks on the row too.
<Switch
checked={sync}
onChange={(e) => setSync(e.target.checked)}
label="Sync across devices"
description="Keeps your settings the same everywhere you sign in"
/>
<Switch
checked={beta}
onChange={(e) => setBeta(e.target.checked)}
label="Beta features"
labelPlacement="start"
/>
<Switch checked readOnly label="Single sign-on" description="Managed by your admin" />Controlled usage
import { useState } from 'react';
import { Switch } from '@unflowio/ui/components/Switch';
function FeatureToggle() {
const [enabled, setEnabled] = useState(false);
return (
<Switch
checked={enabled}
onChange={(e) => setEnabled(e.target.checked)}
aria-label="Enable dark mode"
/>
);
}Uncontrolled usage
<Switch defaultChecked aria-label="Enable notifications" />Read-only vs disabled
Both prevent the user from changing the value, but communicate different semantics:
disabled— the control is not available. Uses HTMLdisabled+aria-disabled="true". The value is excluded from form submission.readOnly— the value is fixed but the control is present and accessible. Usespointer-events-none+aria-readonly="true". The value is included in form submission.
Accessibility
- Renders
<input type="checkbox" role="switch">— natively keyboard-operable (Space to toggle). aria-checkedmirrors thecheckedprop.- With
label, the switch is named by the label text througharia-labelledbyand described bydescriptionthrougharia-describedby. - A console warning fires in development when there is no
label,aria-labeloraria-labelledby.