Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

On and off

Use a switch for one setting that takes effect the moment it flips, with no Save button.

A live on/off setting
Email notifications: On
Show code
<div class="d-flex align-items-center gap-3">
    <app-switch label="Email notifications" name="email-notif" checked="true"></app-switch>
    <span class="wui-text-sm">Email notifications: On</span>
</div>

Default state

Set the starting position for a setting, and leave it to the person to change it.

On and off by default
Auto-renew (on by default)
Beta features (off by default)
Show code
<app-switch label="Auto-renew" name="auto-renew" checked="true"></app-switch>
<app-switch label="Beta features" name="beta-features"></app-switch>

Shape

Keep the round default, and use circle only where a compact control must sit in a tight space.

Round, pill and circle
Round (default): the sliding pill with truly circular ends
Pill: the same sliding pill with squircle ends
Circle: a compact round on/off button
Show code
<app-switch label="Auto-renew" name="auto-renew" checked="true"></app-switch>
<app-switch label="Auto-renew" name="auto-renew" shape="AppCheckShape.Pill" checked="true"></app-switch>
<app-switch label="Auto-renew" name="auto-renew" shape="AppCheckShape.Circle" checked="true"></app-switch>

Validation

Give helper text for guidance, and an error when a setting cannot be left as it is.

Helper text and error
You can change this later.
Notifications are required for this plan.
Show code
<app-switch label="Email notifications" name="email-notif" helper-text="You can change this later."></app-switch>
<app-switch label="Email notifications" name="email-notif" error="Notifications are required for this plan."></app-switch>

Control only

Control only draws just the switch, for a dense form that draws its own labels and messages.

Control only
Show code
<label class="d-flex gap-2 align-items-center"><app-switch control-only="true" name="co-alerts" /> Email alerts</label>

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) unchecked
checked="true"
defaultChecked (React): the starting state

disabled

disabled (unchecked)
disabled checked="true"

read-only

(default) not read-only
read-only="true"

loading

(default) not loading
loading="true"

label

(no label)
label="Auto-renew"
child content, rich markup label

id: 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."
You can change this later.
error="Notifications are required for this plan."
Notifications are required for this plan.
helper-text + error together: error wins
You can change this later.
Notifications are required for this plan.

help: 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 value

className: 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 messages

Guidance

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

Do

An on/off setting that applies right away. The switch reads as a live control.

Avoid

A checkbox reads as a form field to submit later, the wrong signal for an instant toggle.

Caption every switch

Do

Each switch is captioned, so the user knows exactly what it controls and its current state.

Avoid

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.

round pill circle
unset sm md lg
React, generated from the controls
<AppSwitch label="Email notifications" name="notifications" />
Razor, the same props
<app-switch label="Email notifications" name="notifications" />

16 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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 pairs

Use a switch for instant settings

Do

An on/off setting that applies right away. The switch reads as a live control.

Avoid

A checkbox reads as a form field to submit later, the wrong signal for an instant toggle.

Caption every switch

Do

Each switch is captioned, so the user knows exactly what it controls and its current state.

Avoid

A bare switch with no caption leaves the user guessing what it turns on.