Vastu

Switch <va-switch>

Turns a setting on or off, with immediate effect.

When to use it

Use it
For a setting that applies as soon as it changes, such as "Dark theme" or "Email notifications".
Don't use it
For a choice that is only applied when a form is submitted, or for agreeing to terms.
Use instead
va-checkbox for choices submitted with a form.

Examples

Settings

Each switch applies its setting straight away.

Email notifications Dark theme Uses darker colours for this page. Sync (needs an account)
<va-switch checked>Email notifications</va-switch>
<va-switch>
  Dark theme
  <span slot="description">Uses darker colours for this page.</span>
</va-switch>
<va-switch disabled>Sync (needs an account)</va-switch>

In a form

A switch submits name=value while it's on, and resets with its form.

Weekly newsletter Save Reset
<form>
  <va-switch name="newsletter" value="weekly" checked>Weekly newsletter</va-switch>
  <va-button type="submit">Save</va-button>
  <va-button type="reset" variant="secondary">Reset</va-button>
</form>

Install and import

npm install @firstprateek/vastu @firstprateek/vastu-tokens
import '@firstprateek/vastu-tokens/lekha.css'; // once per page
import '@firstprateek/vastu/switch';

API

Attributes and properties

AttributePropertyTypeDefaultDescription
checkedcheckedbooleanfalseWhether the switch is on.
valuevaluestring'on'Submitted with name while the switch is on. Defaults to on, as for a native checkbox.
labellabelstring''Accessible name, when there is no visible label text.
namenamestring''Submitted with the form as name=value.
disableddisabledbooleanfalseDisables the control. It can't be focused, changed or submitted.
requiredrequiredbooleanfalseThe control must have a value before its form can be submitted.
—form (read-only)HTMLFormElement | null—The form this control belongs to, if any.
—validity (read-only)ValidityState—The control's validity state, as on native controls.
—validationMessage (read-only)string—The message the browser shows when the control is invalid, or an empty string.

Events

EventDescription
changeWhen the user flips the switch. Read event.target.checked.
inputWhen the user flips the switch, just before change.

Slots

SlotDescription
(default)The visible label. Clicking it flips the switch.
descriptionOptional help text under the label.

Methods

MethodDescription
checkValidity()Returns true if the control is valid; otherwise fires invalid and returns false.
reportValidity()Like checkValidity(), but also shows the browser's message to the user.

Styling

Components read the brand's tokens. To adjust one component, set its custom properties or style its parts.

Custom propertyTypeDescription
--va-switch-track<color>Track colour when off.
--va-switch-track-on<color>Track colour when on.
--va-switch-thumb<color>Thumb colour.
PartDescription
::part(control)The switch's track (a native button with role="switch").
::part(thumb)The round thumb.
::part(label)The label text.

Accessibility

Role
switch
Accessible name
The slotted label text, or the label attribute when there is no visible label.
Note
The state is announced as on or off, not checked or unchecked.

Keyboard

KeyDoes
SpaceTurns the switch on or off.
EnterTurns the switch on or off.
TabMoves focus to the next control.

Every row on this page is checked by contract tests generated from the same manifest, in Chromium, Firefox and WebKit. Read the manifest.