On this page
@addTagHelper *, Webority.Ui.RazorOn and off
Use a switch for one setting that takes effect the moment it flips, with no Save button.
Default state
Set the starting position for a setting, and leave it to the person to change it.
Shape
Keep the round default, and use circle only where a compact control must sit in a tight space.
Validation
Give helper text for guidance, and an error when a setting cannot be left as it is.
Control only
Control only draws just the switch, for a dense form that draws its own labels and messages.
Every option
Every value of every prop, one cell each.
shape: all three
shape="round" (default)shape="pill"shape="circle"size: all three
size="sm"size="md" (default)size="lg"checked state
(default) uncheckedchecked="true"defaultChecked (React): the starting statedisabled
disabled (unchecked)disabled checked="true"read-only
(default) not read-onlyread-only="true"loading
(default) not loadingloading="true"label
(no label)label="Auto-renew"child content, rich markup labelid: the label points at it
id="notify-email" (the label points at it)name: posted with the form
name="notifications" (posted under it)value: posted when on
value="yes" (posted when on)required
required="true"validation: helper text, error, and error winning over helper text
helper-text="You can change this later."error="Notifications are required for this plan."helper-text + error together: error winshelp: info-tip after the label
help="Sends one email for each new message."help label
(default) help-label="More information"help-label="About alerts"controlOnly: the switch drawn alone
control-only="true"onChange: a callback
onChange(e) (React): fires on every flip; Razor reads the posted form valueclassName: extra classes on the wrapper
class="mb-0"ref: React only, no visible effect
ref (React): forwarded to the input for register()asp-for: Razor only, bound to a model
asp-for: binds name, id, checked and messagesGuidance
What to do, and what to avoid.
Use it when
- A single on/off setting that takes effect immediately.
- Toggling a live feature or preference: dark mode, notifications, a feature flag.
- A binary state where "instant" is the mental model, not "save later".
Reach for something else when
- The opt-in is saved with the rest of a form. → AppCheckbox
- The user picks one of several exclusive options. → AppRadio
- It triggers an action rather than holding a state. → AppButton
- The user selects several values from a list. → AppSelect mode="multiple"
Use a switch for instant settings
An on/off setting that applies right away. The switch reads as a live control.
A checkbox reads as a form field to submit later, the wrong signal for an instant toggle.
Caption every switch
Each switch is captioned, so the user knows exactly what it controls and its current state.
A bare switch with no caption leaves the user guessing what it turns on.
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
16 props. The 5 most used come first.
Used on most screens 5 props
| Prop | Type | Default | Description |
|---|---|---|---|
| labeldefault - | string | - | The visible label rendered beside the switch. Rich markup (a link, emphasis) can be written as child content instead. It renders unencoded. |
| namedefault - | string | - | The field name the switch posts under in a form. |
| checkeddefault false | bool | false | Controlled on or off state. Pair it with onChange. |
| disableddefault false | bool | false | Locks the switch and dims it. |
| helper-textdefault - | string | - | Helper text shown below the control. It is hidden while an error shows. |
Less common 11 props
| Prop | Type | Default | Description |
|---|---|---|---|
| iddefault - | string | - | The id of the switch input, which its label points at. A generated id is used when none is given. |
| valuedefault - | string | - | Submitted value when on. |
| shapedefault round | round | pill | circle | round | The track shape. round is the sliding pill with circular ends, pill is the same pill with squircle ends, and circle is a compact round on/off button. |
| read-onlydefault false | bool | false | Shows the value but blocks editing. The value still posts. |
| loadingdefault false | bool | false | Shows a busy state and blocks input while data loads. |
| sizedefault md | sm | md | lg | md | The control size: sm, md or lg. |
| helpdefault - | string | - | Content for the info-tip after the label. Shown only when a label is set. |
| help-labeldefault More information | string | More information | aria-label for the info-tip button. |
| requireddefault false | bool | false | Marks the input as required. Also a pass-through attribute, not a bound property. |
| errordefault - | string | - | Error message shown below the control. It replaces the helper text and marks the switch invalid. |
| asp-fordefault - | ModelExpression | - | Razor-only. Binds name, id, checked state, label and validation message from a Razor Pages model property. |
Screen reader
3 notes- The control is a native checkbox input, so Space toggles it and it posts with a form.
- label draws a real label tied to the input by id, using a generated id when none is given.
- An error sets aria-invalid to true and is linked to the input with aria-describedby; helper text is linked the same way while no error shows.
Do and avoid
2 pairsUse a switch for instant settings
An on/off setting that applies right away. The switch reads as a live control.
A checkbox reads as a form field to submit later, the wrong signal for an instant toggle.
Caption every switch
Each switch is captioned, so the user knows exactly what it controls and its current state.
A bare switch with no caption leaves the user guessing what it turns on.