Switch | Fragments

Preview

<StatefulSwitch label="Email notifications" />

Installation

npx @usefragments/cli add switch

Writes src/fragments/ui/components/Switch plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

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"
/>

Sizes

Three track sizes: sm, md, lg.

<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
  <StatefulSwitch size="sm" defaultChecked label="Small switch" />
  <StatefulSwitch size="md" defaultChecked label="Medium switch (default)" />
  <StatefulSwitch size="lg" defaultChecked label="Large switch" />
</div>

Disabled States

Locked off and locked on, both dimmed.

<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
  <Switch disabled label="Premium feature (upgrade required)" />
  <Switch disabled 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"
  />

API

Component props
Prop	Type	Default	Description
`checked`	`boolean`	`false`	Whether the switch is in the on state
`defaultChecked`	`boolean`	Not set	Default checked state (uncontrolled)
`onCheckedChange`	`function`	Not set	Called when the switch is toggled: (checked: boolean) => void
`onChange`	`function`	Not set	Alias for onCheckedChange: (checked: boolean) => void
`label`	`string`	Not set	Visible label text
`helperText`	`string`	Not set	Helper text shown below the label (preferred)
`description`	`string`	Not set	Deprecated alias for helperText
`disabled`	`boolean`	`false`	Whether the switch is non-interactive
`size`	`enumsmmdlg`	`md`	Switch track size
`className`	`string`	Not set	—
`name`	`string`	Not set	—
`id`	`string`	Not set	—
`aria-label`	`string`	Not set	—
`aria-labelledby`	`string`	Not set	—
`aria-describedby`	`string`	Not set	—
`form`	`string`	Not set	—
`inputRef`	`union`	Not set	—
`readOnly`	`boolean`	`false`	—
`required`	`boolean`	`false`	—
`uncheckedValue`	`string`	Not set	—
`value`	`string`	Not set	—

Accessibility

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

Standards

Guidance

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)

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

Next steps

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