LumeoA11yfocus-managedalertswitchDepends onformlabelspinnerTested
Tier 3 · 59 testsView source ↗Switch
A control that allows the user to toggle between two states.
Installation
dotnet add package Lumeo
One-time app setup (AddLumeo(), CSS & JS) is covered in the
installation guide.
Usage
@using Lumeo <Switch />
59 tests across 12 files. Auto-generated from the test suite.
When to Use
- Toggle binary settings such as on/off, enabled/disabled, or active/inactive
- Control feature flags or preferences in settings panels
- Provide instant feedback when a state change takes effect immediately
- Replace checkboxes when the toggle represents a real-time switch rather than a form submission
- Build notification preference panels with multiple independent toggles
<FormField>.
See Form › Validation Pattern.
Dark Mode is on
Email Notifications
Receive emails about account activity.
Marketing Emails
Receive emails about new products and features.
Security Alerts
Receive alerts about unusual activity.
Pick a size to see the switch scale live.
On supported mobile browsers, toggling this switch triggers a short vibration via navigator.vibrate(10). Desktop browsers silently no-op.
A switch renders as a <button>, which posts nothing on its own. Set Name and a hidden bubble input is added so the switch's checked state submits in a native form; Value is the string sent when on.
Styling hooks (data-state)
Both the track and thumb expose a data-state
attribute of checked or
unchecked, so you can drive custom CSS
(e.g. data-[state=checked]:bg-primary)
without watching the C# state.
Keyboard Interactions
| Key | Action |
|---|---|
| Space | Toggle the switch between on and off |
| Tab | Move focus to the next focusable element |
Parameter Coverage
Every Lumeo.Size value plus the key bool parameters demoed exhaustively.
Size
Checked
Checked = false
Checked = true
Disabled
Disabled = false
Disabled = true
Loading
Loading = false
Loading = true
API Reference
Switch
| Prop | Type | Default | Description |
|---|---|---|---|
| Required | bool | false | Marks the field as required, setting aria-required and (outside a FormField) the bubble checkbox's required, plus appending a destructive-colored asterisk to the label. |
| Invalid | bool | false | Forces the invalid/error visual state (destructive ring) and aria-invalid, independent of the ambient FormField's validation state. |
| ErrorText | string? | — | Error message shown below the switch (outside a FormField) when Invalid is set. Takes precedence over HelperText. |
| HelperText | string? | — | Helper text shown below the switch (outside a FormField) when there is no error to display. |
| Label | string? | — | Label text rendered before the switch (outside a FormField, which supplies its own label), linked via for/id so clicking it toggles the switch. |
| Name | string? | — | HTML name for the hidden bubble checkbox that mirrors the switch state, so it posts in a native <form> (a plain <button> posts nothing). Falls back to a composing FormField's Name when unset. |
| Value | string? | — | Value submitted for this switch in a native <form> POST when Name is set and the switch is on. Mirrors the native checkbox default of "on". |
| Checked | bool | false | Whether the switch is on. Controlled together with CheckedChanged; when left unbound the switch tracks its own toggles internally. |
| Disabled | bool | false | When true, the switch cannot be toggled and renders with reduced opacity. |
| Loading | bool | false | When true, shows a small spinner in the thumb, disables toggling, and sets aria-busy — for an in-flight async state change. |
| OnLabel | string? | — | Text shown next to the switch (and used as a fallback accessible name) while it is on. |
| OffLabel | string? | — | Text shown next to the switch (and used as a fallback accessible name) while it is off. |
| AriaLabel | string? | — | Accessible name for the switch button, exposed via aria-label. Recommended for icon-only switches that have no visible text. If omitted but OnLabel/OffLabel are set, the current one is used automatically so screen readers announce the switch's purpose. |
| Size | Lumeo.Size | Lumeo.Size.Md | Switch size. Supports Sm, Md (default), Lg. |
| Animated | bool | false | When true, the thumb animates with a bouncy spring cubic-bezier timing instead of the default linear transition. Default is false. |
| HapticFeedback | bool | false | When true, triggers a short haptic vibration via navigator.vibrate() each time the switch is toggled. Silently no-ops on browsers without the Vibration API (e.g. iOS Safari). Default is false. |
| Class | string? | — | Additional CSS classes merged onto the switch's track button. |
| AdditionalAttributes | Dictionary<string, object>? | — | Captures any unmatched attributes and applies them to the switch's track button (a splatted id is stripped inside a FormField so the generated id keeps the label wired up). |
Events
| CheckedChanged | EventCallback<bool> | Fires when the user toggles the switch, with the new checked state. |
Related Components
- Checkbox — Use when the selection is part of a form that is submitted, rather than an instant toggle
- Toggle — Use for toolbar-style on/off buttons with icon support
- RadioGroup — Use when selecting one option from multiple mutually exclusive choices