Switch

<quiet-switch>

stable

since 1.0

Switches let the user toggle between two mutually exclusive states, such as on and off.

Kitten mode

<quiet-switch name="mode" value="kitten">Kitten mode</quiet-switch>

Examples Jump to heading

Checked initially Jump to heading

Add the checked attribute to check the switch initially.

Kitten mode

<quiet-switch name="mode" value="kitten" checked>Kitten mode</quiet-switch>

Adding inner labels Jump to heading

Use the on and off slots to show inner labels or icons that align with the switch's checked state. Space is very limited, so make sure the labels are short enough to fit.

              
                Kitten mode
                on
                off
              
                Kitten mode

<quiet-switch name="mode" value="kitten">
  Kitten mode
  <span slot="on-label">on</span>
  <span slot="off-label">off</span>
</quiet-switch>

<quiet-switch name="mode" value="kitten">
  Kitten mode
  <quiet-icon slot="on-label" name="check" label="On"></quiet-icon>
  <quiet-icon slot="off-label" name="x" label="Off"></quiet-icon>
</quiet-switch>

Changing the size Jump to heading

Use the size attribute to change the text field's size.

              Extra small
              Small
              Medium
              Large
              Extra large
            

<quiet-switch size="xs">Extra small</quiet-switch>
<quiet-switch size="sm">Small</quiet-switch>
<quiet-switch size="md">Medium</quiet-switch>
<quiet-switch size="lg">Large</quiet-switch>
<quiet-switch size="xl">Extra large</quiet-switch>

Disabling Jump to heading

Use the disabled attribute to disable the switch.

              Unchecked and disabled

              Checked and disabled

<quiet-switch disabled>Unchecked and disabled</quiet-switch><br>
<quiet-switch checked disabled>Checked and disabled</quiet-switch>

Validation Jump to heading

The required attribute can be applied to enable validation using the Constraint Validation API. This will prevent form submission until the switch is checked.

<form action="about:blank" method="get" target="_blank">
  <quiet-switch name="sleep" value="zzz" required>Sleep mode</quiet-switch>
  <br><br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

Using custom validation Jump to heading

Use the custom-validity attribute to make the switch invalid and show a custom error message on submit. This will override all other validation parameters. To clear the error, remove the attribute or set it to an empty string.

<form action="about:blank" method="get" target="_blank">
  <quiet-switch name="sleep" value="zzz" required custom-validity="Have you taken a nap first?">Sleep mode</quiet-switch>
  <br><br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

Most validation attributes work exactly like their native counterparts. However, the custom-validity attribute is offered in lieu of the setCustomValidity() method. This allows you to declaratively set custom errors instead of having to call a method with JavaScript.

Styling validation Jump to heading

You can style valid and invalid switches using the :valid and :invalid pseudo classes.

<form action="about:blank" method="get" target="_blank" class="switch__validation-pseudo">
  <quiet-switch name="sleep" value="zzz" required>Sleep mode</quiet-switch>
  <br><br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .switch__validation-pseudo {
    quiet-switch:valid {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-switch:invalid {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

However, these selectors will match even before the user has had a chance to fill out the form. More often than not, you'll want to use the user-valid and user-invalid custom states instead. This way, validation styles are only shown after the user interacts with the form control or when the form is submitted.

<form action="about:blank" method="get" target="_blank" class="switch__validation-custom">
  <quiet-switch name="sleep" value="zzz" required>Sleep mode</quiet-switch>
  <br><br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .switch__validation-custom {
    quiet-switch:state(user-valid) {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-switch:state(user-invalid) {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN

npm

To manually import <quiet-switch> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet@1.0.0/dist/components/switch/switch.js';

To manually import <quiet-switch> from npm, use the following code.

import '@quietui/quiet/dist/components/switch/switch.js';

Slots Jump to heading

Switch supports the following slots. Learn more about using slots

Name	Description
(default)	The switch's label. For plain-text labels, you can use the `label` attribute instead.
`off-label`	The label to show when the switch is off.
`on-label`	The label to show when the switch is on.

Properties Jump to heading

Switch has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute	Description	Type	Default
`associatedForm`	A reference to the `<form>` associated with the form control, or `null` if no form is associated.	`HTMLFormElement null`	`null`
`label`	The switch's label. If you need to provide HTML in the label, use the `label` slot instead.	`string`
`description`	The switch's description. If you need to provide HTML in the description, use the `description` slot instead.	`string`
`name`	The name of the switch. This will be submitted with the form as a name/value pair.	`string`
`value`	The switch's value.	`string`	`''`
`checked`	The switch's checked state.	`boolean`	`false`
`disabled`	Disables the switch.	`boolean`	`false`
`size`	The switch's size.	`'xs' 'sm' 'md' 'lg' 'xl'`	`'md'`
`form`	The form to associate this control with. If omitted, the closest containing `<form>` will be used. The value of this attribute must be an ID of a form in the same document or shadow root.	`string`
`required`	Makes the switch required. Form submission will not be allowed until the switch is checked.	`boolean`	`false`
`customValidity` `custom-validity`	You can provide a custom error message to force the switch to be invalid. To clear the error, set this to an empty string.	`string`	`''`

Methods Jump to heading

Switch supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods

Name	Description	Arguments
`focus()`	Sets focus to the switch.
`blur()`	Removes focus from the switch.
`checkValidity()`	Checks if the form control has any restraints and whether it satisfies them. If invalid, `false` will be returned and the `invalid` event will be dispatched. If valid, `true` will be returned.
`reportValidity()`	Checks if the form control has any restraints and whether it satisfies them. If invalid, `false` will be returned and the `invalid` event will be dispatched. In addition, the problem will be reported to the user. If valid, `true` will be returned.

Events Jump to heading

Switch dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name	Description
`quiet-blur`	Emitted when the switch loses focus. This event does not bubble.
`quiet-change`	Emitted when the user commits changes to the switch's value.
`quiet-focus`	Emitted when the switch receives focus. This event does not bubble.
`quiet-input`	Emitted when the switch receives input.

CSS parts Jump to heading

Switch exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name	Description	CSS selector
`label`	The `<label>` that wraps the entire control.	`::part(label)`
`visual-box`	The element that wraps the internal switch.	`::part(visual-box)`
`switch`	The internal switch, an `<input type="checkbox" role="switch">` element.	`::part(switch)`
`thumb`	The switch's thumb.	`::part(thumb)`
`on-label`	The container wrapping the `on-label`.	`::part(on-label)`
`off-label`	The container wrapping the `off-label`.	`::part(off-label)`

Custom States Jump to heading

Switch has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name	Description	CSS selector
`disabled`	Applied when the switch is disabled.	`:state(disabled)`
`focused`	Applied when the switch has focus.	`:state(focused)`
`user-valid`	Applied when the switch is valid and the user has sufficiently interacted with it.	`:state(user-valid)`
`user-invalid`	Applied when the switch is invalid and the user has sufficiently interacted with it.	`:state(user-invalid)`

Dependencies Jump to heading

Switch automatically imports the following elements. Sub-dependencies are also included in this list.

<quiet-icon>

Switch

Examples Jump to heading #

Checked initially Jump to heading #

Adding inner labels Jump to heading #

Changing the size Jump to heading #

Disabling Jump to heading #

Validation Jump to heading #

Using custom validation Jump to heading #

Styling validation Jump to heading #

API Jump to heading #

Importing Jump to heading #

Slots Jump to heading #

Properties Jump to heading #

Methods Jump to heading #

Events Jump to heading #

CSS parts Jump to heading #

Custom States Jump to heading #

Dependencies Jump to heading #