Switch
The e-switch component captures boolean or mapped binary state with the shared field contract, including helper details, async loading feedback, validation, and accessible labeling.
Use this page to validate toggle behavior, side effects, and value mapping before wiring preference panels, release gates, or environment settings into production flows.
Usage
Use this baseline playground to tune switch behavior in context: color, outlined, disabled, readonly, loading, and retain-color for stronger state continuity.
Visual variants
Compare default, outlined, tonal, retain-color, loading, disabled, and readonly states to keep binary decisions clear in dense configuration panels.
Custom values
Map the switch state to domain values with true-value and false-value when the backing model is not strictly boolean.
Loading and async flows
Use loading to block interaction while persisting the new value and to make side effects explicit during async preference updates.
Named slots
Use the label slot to render richer inline labels with links or policy context while preserving switch semantics.
Validation
Validate consent or environment requirements with explicit submit-state feedback before allowing a critical transition.
Submit to validate the switch rule.
Props
Use the API table as the source of truth for accepted types, defaults, and inherited field behavior.
| Property | Type | Default |
|---|---|---|
| modelValue | boolean | string | number | undefined |
Current switch value. Active state is resolved by strict equality against trueValue. | ||
| trueValue | boolean | string | number | true |
Value emitted when the switch becomes active. | ||
| falseValue | boolean | string | number | false |
Value emitted when the switch becomes inactive. | ||
| loading | boolean | false |
Makes the control non-interactive and shows an inline loading indicator in the thumb. | ||
| tonal | boolean | false |
Shows field overlay styling inside the switch control without changing binary behavior. | ||
| hideOverlay | boolean | false |
Hides the shared field overlay visual without changing switch behavior. | ||
| clearable | boolean | false |
Shows clear action when a value exists. | ||
| color | string | "primary" |
Base theme color applied to field state and interactions. | ||
| outlined | boolean | false |
Uses outlined visual variant for the field container. | ||
| disabled | boolean | false |
Disables interaction and prevents value updates. | ||
| readonly | boolean | false |
Prevents editing while preserving focus behavior. | ||
| dense | boolean | false |
Applies denser vertical spacing inherited from Field. | ||
| retainColor | boolean | false |
Keeps active color styling after focus/interaction. | ||
| label | string | number | undefined |
Field label text. | ||
| labelMinWidth | string | number | undefined |
Minimum width reserved for label region. | ||
| labelBehavior | "static" | "static" |
Label behavior is static for switch controls. | ||
| inputAlign | left | right | center | start | end | "start" |
Horizontal text alignment inside input/selection area. | ||
| prependIcon | string | IconPath | IconPath[] | undefined |
Icon rendered in outer-left affix region. | ||
| prependInnerIcon | string | IconPath | IconPath[] | undefined |
Icon rendered before content inside input frame. | ||
| appendInnerIcon | string | IconPath | IconPath[] | undefined |
Icon rendered after content inside input frame. | ||
| appendIcon | string | IconPath | IconPath[] | undefined |
Icon rendered in outer-right affix region. | ||
| detail | string | undefined |
Helper text shown in details area when no errors are present. | ||
| detailsOnMessageOnly | boolean | false |
Shows details area only when messages/errors exist. | ||
| rules | FieldRule | undefined |
Validation rules evaluated against modelValue. | ||
| detailErrors | string[] | undefined |
Explicit error messages rendered in details area. | ||