React Switch component

Preview

<StatefulSwitch label="Email notifications" />

Usage

Use when

Settings that apply the moment they change
Turning a feature on or off in a settings panel
The result is visible straight away

Avoid when

Choices that only apply on submit (use Checkbox)
Several options at once (use a Checkbox group)
Yes/no questions in a form (use RadioGroup)
More than two states (use Select or RadioGroup)

Implementation notes

The label names what is being turned on
On always means enabled, never the reverse
Apply the change immediately — no save button
Add helperText when the label alone is ambiguous
Stack related switches together

Installation

pnpm add @usefragments/ui

Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Examples

Checked

Starts on; the track fills with the accent colour.

<StatefulSwitch defaultChecked label="Dark mode" />

With Helper Text

Second line says what the setting actually does.

<StatefulSwitch
  defaultChecked
  label="Auto-save"
  helperText="Automatically save changes as you type"
/>

Disabled and Read-only

Disabled dims once; read-only keeps full ink and refuses the toggle.

<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
  <Switch disabled label="Premium feature (upgrade required)" />
  <Switch readOnly checked label="System managed (read-only)" />
</div>

Settings Panel

Stacked switches sharing one rhythm and helper column.

<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '320px' }}>
  <StatefulSwitch
    defaultChecked
    label="Push notifications"
    helperText="Receive push notifications on your device"
  />

Invalid

A message with an icon under the label; the track keeps its colours.

<StatefulSwitch
  label="Share findings with the team"
  invalid
  errorMessage="Sharing is off on this plan."
/>

API reference

Component props
Prop	Type	Default	Description
`aria-describedby`	`string \| undefined`	Not set	—
`aria-label`	`string \| undefined`	Not set	—
`aria-labelledby`	`string \| undefined`	Not set	—
`checked`	`boolean \| undefined`	`false`	Whether the switch is in the on state
`defaultChecked`	`boolean \| undefined`	Not set	Default checked state (uncontrolled)
`disabled`	`boolean \| undefined`	`false`	Whether the switch is non-interactive
`errorMessage`	`React.ReactNode`	Not set	Message shown with a warning icon under the label while invalid; wired to aria-describedby
`form`	`string \| undefined`	Not set	—
`helperText`	`string \| undefined`	Not set	Helper text shown below the label (preferred)
`id`	`string \| undefined`	Not set	ID for the hidden input
`inputRef`	`React.Ref<HTMLInputElement> \| undefined`	Not set	—
`invalid`	`boolean \| undefined`	`false`	The value fails validation: errorMessage shows under the label with an icon
`label`	`string \| undefined`	Not set	Visible label beside the track (outside the switch element, tied by aria-labelledby)
`name`	`string \| undefined`	Not set	—
`onCheckedChange`	`((checked: boolean) => void) \| undefined`	Not set	Called with the next state when the user toggles the switch
`readOnly`	`boolean \| undefined`	`false`	The switch cannot be toggled; an off track takes the band and a dashed edge
`required`	`boolean \| undefined`	`false`	The switch must be on before the form submits
`uncheckedValue`	`string \| undefined`	Not set	—
`value`	`string \| undefined`	Not set	—
`className`	`string \| undefined`	Not set	Class on the outer element: the label row, or the track when there is no visible text

Accessibility

role="switch" with aria-checked
Every switch has a label, visible or aria-label
Focus ring stays visible
Flipping it is announced

Standards references

InputsiblingInput handles text/number entry; Switch handles boolean state
CheckboxalternativeUse Checkbox when change requires form submission

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.