Component v1.1.0 Forms

Switch

Accessible boolean switch with label, helper text, and Angular forms support.

API Stable 2.1 WCAG notes Ready Dark mode
Selector
ui-switch
Package
@ngnova/ui/switch

Import

Standalone Tailwind v4
import { UiSwitchComponent } from '@ngnova/ui/switch';

Usage & variants

Live examples use the public ui-switch API, paired with the exact snippet a product team would paste into an Angular app.

API Reference

Release notifications

Accessible boolean switch with label, helper text, and Angular forms support.

Production guidance

Use these notes to decide when the component belongs in a product workflow and what to verify before shipping.

When to use

Use for settings that can be toggled independently, such as notifications or feature flags.

Watch for

Do not use Switch for actions that require confirmation; use Button or Modal instead.

Product recipes

Apply Switch in distinct, copyable product scenarios—not just an isolated component state.

Notification setting

Boolean state stays in the parent form control.

Angular template ui-switch-recipe.example.html
1
2
3
4
5
<ui-switch
  label="Release notifications"
  helperText="Boolean state stays in the parent form control."
  [formControl]="notifications"
/>

Privacy preference

Use a switch for an immediately applied setting and explain the consequence beside it.

Angular template ui-switch-recipe.example.html
1
2
3
4
5
<ui-switch
  label="Show profile to workspace members"
  helperText="Your name, role, and avatar will be visible in member search."
  [formControl]="profileVisibility"
/>

API Reference

Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.

Inputs

label ''
string

Visible switch label.

helperText ''
string

Support text shown below the label.

inputId generated
string

ID applied to the native checkbox.

name ''
string

Native input name.

ariaLabel ''
string

Accessible label when no visible label is provided.

disabled false
boolean

Disables the switch.

required false
boolean

Marks the switch as required.

Outputs

valueChange OutputEmitterRef<boolean>

Emits the checked value after user interaction.

focused OutputEmitterRef<FocusEvent>

Emits when the switch receives focus. The host also forwards a native focus event.

blurred OutputEmitterRef<FocusEvent>

Emits when the switch loses focus. The host also forwards a native blur event.

Accessibility

  • Uses role="switch" on a native checkbox pattern and exposes checked state.
  • The wrapping label provides the accessible name; provide ariaLabel only when visible label text is omitted.
  • Helper text is associated with the native switch through aria-describedby.

Keyboard behavior

  • Space toggles the switch.
  • Tab moves focus to the switch.

Testing guidance

  • Assert checked state, valueChange, CVA disabled state, focus, and blur outputs.