Toggle Switch

Demo & usage

More examples

<sv-toggle-switch label="Small" size="sm" [(checked)]="a" />
<sv-toggle-switch label="Success" variant="success" [(checked)]="b" />

<sv-toggle-switch onLabel="On" offLabel="Off" [(checked)]="enabled" />

<sv-toggle-switch
  formControlName="acceptTerms"
  label="I accept the terms"
  description="You must accept to continue."
  [required]="true" />

<sv-toggle-switch
  label="Two-factor authentication"
  [checked]="twoFactor()"
  [pending]="saving()"
  [error]="failure()"
  (toggleRequest)="save($event)" />

save(e: SvToggleChange): void {
  this.saving.set(true);
  this.api.setTwoFactor(e.checked, e.requestKey).subscribe({
    next:  () => this.saving.set(false),
    error: () => { e.rollback(); this.failure.set('Could not save that.'); this.saving.set(false); },
  });
}

<!-- The value has not arrived. Nothing on screen is trustworthy yet. -->
<sv-toggle-switch label="Email digest" [loading]="settings.isLoading()" />

<!-- The value is the user's own choice, and the write is out. -->
<sv-toggle-switch label="Email digest" [checked]="digest()" [pending]="saving()" />

<sv-toggle-switch
  label="Single sign-on"
  [checked]="true"
  lockReason="Enforced by your organization" />

When to use

• Toggling a single setting that takes effect immediately (no Save needed).
• The choice is binary and the default is meaningful — e.g. notifications on/off.
• Use a Checkbox instead whenever the change only lands on submit — a form field, a terms acceptance, a row selection, or anything a Cancel button is expected to undo. A switch promises "this is on now", so putting one inside a form with a Save button makes a promise the form then breaks; and if the user closes the dialog, nothing tells them which of the two things they saw was true.
• Use a Checkbox instead when the action needs confirming. A switch cannot ask "are you sure" without contradicting itself: it has already moved by the time the dialog opens, and a cancelled confirmation leaves it to move back on its own — which is indistinguishable from a failed save.

Async states

• loading
• error

Server writes

Writes

• toggleRequest

Each payload carries a requestKey — send it with the request so a retry cannot apply the same change twice.

Rollback

Call event.rollback() when the save fails — the change is already on screen, and this is what puts it back.

While saving

Bind pending — with two writes outstanding there is no single state to roll back to, so the action stays locked until the first one lands.

On failure

Pass the failure to error to show it in place — without taking away what the user was working on.

Outputs

Customization & theming

• Set `size` (xs, sm, md, lg) and `variant` (primary, success, warning, danger, neutral) for the active color.
• Place the label with `labelPosition` (right, left, top, hidden), add a `description` line and inline `onLabel` / `offLabel` track text.
• Show inline `onIcon` / `offIcon` icons inside the thumb; toggle `disabled`, `loading` and `required`.
• Two-way bind with `[(checked)]` or bind a reactive control; listen to `(toggled)` for the new boolean, or `(toggleRequest)` for a `{ checked, requestKey, rollback }` payload when a server has to agree.
• `pending` locks the switch while a write is in flight without dimming it; `lockReason` locks it and says why.

Best practices

• Do: Phrase the `label` as the enabled state ("Email notifications"), not a question.
• Do: Apply the change instantly on toggle, and bind `[pending]` — not `[loading]` — while it persists. `loading` is for a value you do not have yet; `pending` is for one the user just chose.
• Do: Handle `(toggleRequest)` for anything that reaches a server: send its `requestKey` so a retried request cannot land twice, and call its `rollback()` on failure so the switch does not sit there lying.
• Do: Report the failure as well as reverting. A switch that moves back on its own, with nothing said, is the exact experience this contract exists to prevent — bind `[error]`. Not `[serverError]`: that one self-expires on the next value change, and a rollback IS a value change, so the message would clear in the same tick it appeared.
• Don't: Don't use a toggle when the user must explicitly submit — that's a checkbox's job.
• Don't: Don't reach for `[disabled]` when you know why it is locked. `lockReason` says so, and keeps the switch focusable so the explanation is reachable.
• Tip: Set `ariaLabel` when there is no visible `label`.

Accessibility

• Uses `role="switch"` with `aria-checked`; operable with Space/Enter and a visible focus ring.
• The visible `label` is associated via `<label for>`, so clicking the text toggles the switch; a unique id is generated automatically when `inputId` is omitted.
• The accessible name comes from `aria-labelledby` (visible label) or `ariaLabel` (hidden); `description` is linked with `aria-describedby`.
• `required` sets `aria-required`; `loading` and `pending` both set `aria-busy`; `disabled`, `pending`, `lockReason` and a programmatic `formControl.disable()` all set `aria-disabled` and block interaction.
• A `lockReason` is rendered as text and linked with `aria-describedby`, and the switch keeps `tabindex="0"` — a lock explained only in a tooltip, or on an unfocusable control, is unreachable by the people most likely to need it.