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.
<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
| Attribute | Property | Type | Default | Description |
|---|
checked | checked | boolean | false | Whether the switch is on. |
value | value | string | 'on' | Submitted with name while the switch is on. Defaults to on, as for a native checkbox. |
label | label | string | '' | Accessible name, when there is no visible label text. |
name | name | string | '' | Submitted with the form as name=value. |
disabled | disabled | boolean | false | Disables the control. It can't be focused, changed or submitted. |
required | required | boolean | false | The 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
| Event | Description |
|---|
change | When the user flips the switch. Read event.target.checked. |
input | When the user flips the switch, just before change. |
Slots
| Slot | Description |
|---|
| (default) | The visible label. Clicking it flips the switch. |
description | Optional help text under the label. |
Methods
| Method | Description |
|---|
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 property | Type | Description |
|---|
--va-switch-track | <color> | Track colour when off. |
--va-switch-track-on | <color> | Track colour when on. |
--va-switch-thumb | <color> | Thumb colour. |
| Part | Description |
|---|
::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
| Key | Does |
|---|
| Space | Turns the switch on or off. |
| Enter | Turns the switch on or off. |
| Tab | Moves 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.