Switch
A native binary control with switch semantics, three Angular Forms adapters, deterministic readonly behavior and complete visual ownership.
GET STARTED
Import
Import the canonical standalone component from its granular entry point.
Binary state
Bind the boolean checked model directly. The projected text labels the native switch and remains clickable.
On and off labels
Optional track labels reinforce state visually. They are decorative, so ariaLabel supplies the accessible name when no visible label is projected.
Every Angular Forms API
Signal Forms, Reactive Forms and template-driven forms share one boolean source of truth.
States and Field composition
Disabled leaves the tab order, readonly remains discoverable without hover feedback, and NeuralField supplies shared validation state.
Semantic events
stateChange fires only for user interaction and includes both values. Programmatic writes only update checkedChange.
No user change yet.
Logical RTL behavior
The thumb travels toward logical end, so the same component mirrors without separate application code.
Unstyled and typed slots
Native behavior and structural state hooks remain while Tailwind owns every visible choice.
Component boundary
Switch intentionally models only boolean state. Use Checkbox for form choices and TriState Checkbox when null or mixed is part of the domain.
ACCESSIBILITY
Native switch semantics
A real checkbox carries browser focus, validation and form behavior while role=switch communicates the binary interface pattern.
Native foundation
The visually hidden input remains the interactive element. checked, disabled, required, name and inputValue map directly to native properties.
Accessible name
Project a concise visible label whenever possible. For icon-only or label-free composition, provide ariaLabel. onLabel and offLabel never replace the accessible name.
Keyboard
Tab focuses the switch and Space toggles it through native browser behavior. No custom key manager is required.
Readonly and disabled
Disabled removes interaction and focus. Readonly uses aria-readonly, stays focusable and restores the previous value when pointer or keyboard activation is attempted.
Field state
Inside NeuralField, the switch inherits its deterministic id, described-by chain, required, invalid, pending, disabled, readonly, fluid and unstyled state.
SSR and hydration
Stable APP_ID-based ids avoid random server markup. Rendering does not touch browser globals and interaction begins after hydration.
PUBLIC CONTRACT
Switch API
Models and inputs
| Name | Type | Default | Purpose |
|---|---|---|---|
| checked | model<boolean> | false | Authoritative binary value; checkedChange supports two-way binding. |
| disabled | boolean | false | Disables the native checkbox. |
| readonly | boolean | false | Keeps focusability while preventing user mutation. |
| required | boolean | false | Enables native required validation. |
| invalid | boolean | false | Exposes ARIA and visual invalid state. |
| pending | boolean | false | Exposes aria-busy on the input. |
| touched / dirty | boolean | false | Forms state inputs retained for adapter parity. |
| fluid | boolean | false | Expands the root to available width. |
| inputId | string | '' | Explicit native input id. |
| name | string | '' | Native form submission name. |
| inputValue | string | 'on' | Native value submitted when checked. |
| ariaLabel | string | '' | Accessible name when no visible label is projected. |
| onLabel / offLabel | string | '' | Optional visual state text inside the track. |
| unstyled | boolean | false | Removes NeuralNg visual classes. |
| switchClass | string | '' | Additive root classes. |
| inputClass | string | '' | Additive native input classes. |
| labelClass | string | '' | Additive projected label classes. |
| classes | NeuralSwitchClasses | {} | Typed visual class slots. |
Outputs
checkedChangebooleanGenerated by the checked model for two-way binding.
stateChangeNeuralSwitchChangeUser-only event with current value, previous value and native event.
touchvoidEmitted when the native input blurs.
Methods
focus(options?)voidFocuses the native checkbox.
reset()voidSets checked to false without a user event.
Typed class slots
rootLabel wrapper and state-hook owner.
inputVisually hidden native checkbox.
trackVisible switch track.
checkedTrackAdditional track classes while checked.
thumbMovable visual thumb.
labelProjected visible label.
onLabelChecked-state track text.
offLabelUnchecked-state track text.
Public types
NeuralSwitchChange{ checked: boolean; previousChecked: boolean; nativeEvent: Event }
NeuralSwitchClassesTyped root, native input, track, thumb, label and state-label slots.
Legacy alias
SwitchComponent remains importable for compatibility, but new code and generated AI context should always use NeuralSwitch.
DESIGN TOKENS
Switch tokens
Neutral supplies production defaults. Glass, Futuristic and consumer themes override this stable contract without changing component logic.
Layout and typography
--neural-switch-gapSpacing between component items.
--neural-switch-widthComponent inline size.
--neural-switch-label-colorLabel foreground color.
--neural-switch-font-familyComponent font family.
--neural-switch-font-sizeComponent font size.
--neural-switch-line-heightComponent line height.
--neural-switch-state-label-font-sizeState label font size.
--neural-switch-state-label-font-weightState label font weight.
Track
--neural-switch-track-widthTrack inline size.
--neural-switch-track-heightTrack block size.
--neural-switch-track-paddingTrack internal spacing.
--neural-switch-track-colorTrack foreground color.
--neural-switch-track-backgroundTrack background surface.
--neural-switch-track-background-hoverHovered track background surface.
--neural-switch-track-background-checkedChecked track background surface.
--neural-switch-track-background-checked-hoverChecked Hovered track background surface.
--neural-switch-track-borderTrack border shorthand.
--neural-switch-track-border-color-hoverHovered track border color.
--neural-switch-track-border-color-checkedChecked track border color.
--neural-switch-track-border-color-focusFocused track border color.
--neural-switch-track-border-color-invalidInvalid track border color.
--neural-switch-track-radiusTrack corner radius.
--neural-switch-track-shadowTrack box shadow.
--neural-switch-track-shadow-focusFocused track box shadow.
Thumb and state
--neural-switch-thumb-sizeThumb width and height.
--neural-switch-thumb-backgroundThumb background surface.
--neural-switch-thumb-background-checkedChecked thumb background surface.
--neural-switch-thumb-radiusThumb corner radius.
--neural-switch-thumb-shadowThumb box shadow.
--neural-switch-thumb-translateLogical travel distance of the Switch thumb in its checked state.
--neural-switch-focus-ringComponent keyboard focus ring.
--neural-switch-focus-ring-offsetComponent focus ring offset.
--neural-switch-disabled-opacityDisabled opacity.
Motion
--neural-switch-transitionComponent CSS transition.
--neural-switch-thumb-transitionThumb CSS transition.