Choice & selection

AppSwitch

A single on/off toggle that takes effect the moment it flips — no Save button.

<app-switch label="Email notifications" name="email-notif" />

A switch flips a single setting on or off, and the change applies immediately — dark mode, email notifications, a live feature flag. That instant, no-Save mental model is what separates a switch from a checkbox: a checkbox waits for the form to submit, a switch acts the moment it moves.

Its look comes entirely from the shared @webority/theme, so the Razor <app-switch> and the React <AppSwitch> render identically — a switch is a switch on every Webority surface.

Playground

Every attribute, live. Each change re-renders the real tag helper on the server, so the markup underneath is the exact call that produced the switch above it.

<app-switch label="Email notifications" name="notifications" />
error wins over hintSet both and only error shows — it also flips aria-invalid to true. Clear the error text in the playground to see the hint reappear.

On and off

Bind checked / onChange to a boolean; the switch reflects it and reports every flip. Pair it with a caption so the user reads what the toggle controls.

A live on/off setting
Flipping the switch updates state at once — there is no separate confirm step.
Email notifications — On
Show code 
<app-switch label="Email notifications" name="email-notif" checked="true" />
A switch acts immediatelyBecause a switch takes effect the instant it flips, use it only where that's true — a setting the app applies right away. If the change is only saved when the user hits Save, a checkbox matches the mental model better.

Default state

Set the starting position with the checked attribute — present (or "true") renders the switch already on, omitted renders it off.

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

Shape

shape takes round (the default sliding pill, truly circular ends), pill (the same sliding pill with squircle ends, the checkbox corner shape), or circle, a compact round on/off button that flips colour in place rather than sliding a knob.

Round, pill and circle
pill keeps the sliding pill but swaps the round ends for squircle ones. Use circle where space is tight; round stays the default.
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 label="Auto-renew" name="auto-renew" shape="pill" checked="true" />
<app-switch label="Auto-renew" name="auto-renew" shape="circle" checked="true" />

Validation

Show a hint for guidance and an error when validation fails. They share one slot below the control — the error replaces the hint, matching app-input.

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

When to use

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. → AppMultiSelect

Best practices

Do
Email notifications — On
An on/off setting that applies right away — the switch reads as a live control.
Don't
A checkbox reads as a form field to submit later — the wrong signal for an instant toggle.
Do
Auto-renew (on by default)
Beta features (off by default)
Each switch is captioned, so the user knows exactly what it controls and its current state.
Don't
A bare switch with no caption leaves the user guessing what it turns on.

Every option

The whole surface of the component, one cell per value.

shape — all three

shape="round"
shape="pill"
shape="circle"

checked state

(default) unchecked
checked="true"

disabled

disabled (unchecked)
disabled checked="true"

label

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

required

required="true"

validation — hint, error, and error winning over hint

hint="You can change this later."
You can change this later.
error="Notifications are required for this plan."
Notifications are required for this plan.
hint + error together — error wins
Notifications are required for this plan.

Attributes

AttributeTypeDefaultDescription
labelstring—The visible label rendered beside the switch. Rich markup (a link, emphasis) can be written as child content instead — it renders unencoded, matching React's ReactNode label.
namestring—Field name for form submission; also derives the input id when id is not set.
idstring—Explicit input id — binds the label's for to it and overrides the name-derived id. Declared property, matching React's id.
valuestring—Submitted value when on.
checkedboolfalseRenders the switch in the on position.
shaperound | pill | circleroundTrack shape: round is the sliding pill with truly circular ends; pill is the same sliding pill with squircle ends; circle is a compact round on/off button.
disabledboolfalseDisables the switch. Declared property, matching React's disabled.
requiredboolfalseMarks the input as required. Also a pass-through attribute, not a bound property.
errorstring—Error message below the control. Turns aria-invalid true and replaces the hint.
hintstring—Helper text below the control. Hidden while an error is shown.
asp-forModelExpression—Razor-only. Binds name, id, checked state, label and validation message from a Razor Pages model property — the nearest equivalent to React's controlled checked/onChange pair.