Skip to main content

Switch

Toggle switches are digital on/off switches. They prompt users to choose between two mutually exclusive options and always have a default value. Toggles should provide immediate results, giving users the freedom to control their preferences as needed.

Definition from NNGroup

Switch vs. checkbox​

Switches and Checkboxes have similar purposes and must be used consistently across your application.

As a rule of thumb, checkboxes store status, whereas switches have an immediate effect (like a light switch in the real world). Checkboxes allow users to change their minds before submitting their choices.

Use switches:

  • when the primary target platform is mobile or tablet
  • when the effect of toggling the switch is immediate

Watch this NNGroup video for examples and additional resources.

Switch sides​

The qds-switch supports optional icons and labels on both sides. Use the *-unchecked and *-checked* properties to control them:

Loading...
Live Editor
<div class="qds-controls qds-related">
  <qds-switch
    checked
    icon-unchecked-name="alarm-clock"
    text-unchecked="Unchecked side"
    icon-checked-name="magnifying-glass"
    text-checked="Checked side"
  ></qds-switch>
  <qds-switch
    checked
    icon-checked-name="magnifying-glass"
    text-checked="Checked side alone"
  ></qds-switch>
  <qds-switch
    icon-unchecked-name="alarm-clock"
    text-unchecked="Unchecked side alone"
  ></qds-switch>
</div>

Note: lack of icons in the new libraries makes this example meaningless. A better example will be provided later.

Why not left and right?​

Quartz supports Right-To-Left (RTL) languages whose reading direction is the opposite of the Latin-derived languages. The switch positions also mirror the direction of the language. Using checked and unchecked removes ambiguity and works with all languages.

Text​

The text-unchecked and text-checked properties set the labels displayed on the respective sides of the switch:

Loading...
Live Editor
<qds-switch text-unchecked="Unchecked" text-checked="Checked"></qds-switch>

Text is optional but highly recommended on at least one side of the switch. In Figma, disable the 🅵 text-unchecked and 🅵 text-checked toggles to hide the labels.

Loading...
Live Editor
<qds-switch text-unchecked="Show advanced info"></qds-switch>

Writing guidelines​

  • Use positive and active wording for single label so that it's clear what will happen if the user turns on the switch
  • Keep labels short to make them scannable

Checked​

Use the checked attribute to toggle the switch on. Clicking on an activated switch will toggle it off.

Loading...
Live Editor
<qds-switch checked text="Enabled"></qds-switch>

Toggle switches should take immediate effect and should not require the user to click "Save" or "Submit" to apply the new state.

Icon​

The icon-unchecked-name and icon-checked-name properties set the icons on the respective sides of the switch:

Loading...
Live Editor
<qds-switch
  icon-unchecked-name="alarm-clock"
  text-unchecked="Alarm"
  icon-checked-name="magnifying-glass"
  text-checked="Zoom"
></qds-switch>

Quartz will look into the default icon library unless you specify another library using the icon-unchecked-library or icon-checked-library properties.

In Figma, enable the 🅵 icon-unchecked or 🅵 icon-checked toggles to see the icon-unchecked-name and icon-checked-name properties. See the Usage > Icons instructions for more details.

Icon-only​

Setting icon-unchecked-name without text-unchecked, or icon-checked-name without text-checked will make the switch show only icons.

In Figma, enable the 🅵 icon-unchecked and 🅵 icon-checked toggles and disable the 🅵 text-unchecked and 🅵 text-checked toggles.

Loading...
Live Editor
<qds-switch
  icon-unchecked-name="alarm-clock"
  icon-checked-name="magnifying-glass"
></qds-switch>

Note: lack of icons in the new libraries makes this example meaningless. A better example will be provided later.

Icon guidelines​

  • Prefer using only labels by default. Add an icon only to give more emphasis to the switch.
  • Don't put icons on every switch.

Size​

Switches follow the transversal control size principles. Use the standard size unless you're in one of the specific contexts described on that page.

Loading...
Live Editor
<div class="qds-controls qds-related">
  <div class="qds-controls qds-related flex flex-row">
    <qds-label text="Standard size:"></qds-label>
    <qds-switch
      text="Select me"
      text-unchecked="Off"
      text-checked="On"
    ></qds-switch>
  </div>
  <div class="qds-controls-large qds-related flex flex-row">
    <qds-label size="large" text="Large size:"></qds-label>
    <qds-switch
      size="large"
      text="Select me"
      text-unchecked="Off"
      text-checked="On"
    ></qds-switch>
  </div>
  <div class="qds-controls-small qds-related flex flex-row">
    <qds-label size="small" text="Small size:"></qds-label>
    <qds-switch
      size="small"
      text="Select me"
      text-unchecked="Off"
      text-checked="On"
    ></qds-switch>
  </div>
</div>

Layout​

Stacking​

On mobile, settings are often displayed using switches located at the opposite edge of the screen. Labels of the switch expand with its width, so it's easy to implement a mobile settings screen layout:

Loading...
Live Editor
<div class="qds-platform-mobile qds-controls qds-related w-[300px]">
  <qds-switch text-unchecked="Option 1" class="w-full"></qds-switch>
  <qds-switch text-unchecked="Option 2" class="w-full"></qds-switch>
  <qds-switch text-unchecked="Option 3" class="w-full"></qds-switch>
</div>

Inlining​

Avoid displaying several switches on the same line.

Set the inline attribute to let the switch labels align nicely with siblings' labels:

Loading...
Live Editor
<div class="qds-controls qds-related flex-row justify-between">
  <div class="qds-controls qds-related flex-row">
    <qds-button text="Button"></qds-button>
    <qds-button text="Button"></qds-button>
  </div>
  <qds-switch inline text-checked="Show hidden items"></qds-switch>
</div>

If the switch labels are too long, they will span over multiple lines, but their baseline will remain aligned with the other controls:

Loading...
Live Editor
<div class="qds-controls qds-related flex-row">
  <qds-button text="Button"></qds-button>
  <qds-switch
    inline
    text-checked="This is a very long label that will span over multiple lines depending on how much space is available on the screen"
  ></qds-switch>
  <qds-button text="Button"></qds-button>
</div>

In forms​

Do not use switches in forms. Use Checkboxes instead.

Additional options​

Disabled​

Use the disabled attribute to disable the switch. Clicks will be suppressed until the disabled state is removed.

Loading...
Live Editor
<qds-switch checked disabled text-checked="Option"></qds-switch>

Implementation tips​

Importing​

Note: if you're using the lazy loader to load Quartz components, you can ignore this section.

To import this component from the public jsDeliver CDN using a JavaScript import:

import { defineCustomElementQdsSwitch } from 'https://cdn.jsdelivr.net/npm/@quartzds/core@next+esm'
defineCustomElementQdsSwitch()

Component reference​

Properties​

Attribute / PropertyTypeDescriptionDefault
autofocus / autoFocus
boolean | undefined

Specify whether the switch should have focus when the page loads.

undefined
checked
boolean | undefined

Sets the switch's state.

undefined
disabled
boolean | undefined

Prevents the switch from being interacted with: it cannot be pressed or focused.

undefined
form
HTMLFormElement | null | string

The <form> element to associate the switch with (its form owner).

The value of this property must be the id of a <form> in the same document. If this property is not set, the <qds-switch> is associated with its ancestor <form> element, if any.

This property lets you associate <qds-switch> elements to <form>s anywhere in the document, not just inside a <form>. It can also override an ancestor <form> element.

null
icon-checked-library / iconCheckedLibrary
string

The name of a registered checked icon library.

'default'
icon-checked-name / iconCheckedName
string | undefined

The name of the checked icon to render.

Available names depend on the icon library being used.

undefined
icon-unchecked-library / iconUncheckedLibrary
string

The name of a registered unchecked icon library.

'default'
icon-unchecked-name / iconUncheckedName
string | undefined

The name of the unchecked icon to render.

Available names depend on the icon library being used.

undefined
inline
boolean

Adds vertical margin to the switch for alignment.

This is useful when creating inline layouts so that the first lines have the correct vertical centering.

false
name
string | undefined

The name of the switch, which is submitted with the form data.

undefined
size
"large" | "small" | "standard" | undefined

The switches's size.

'standard'
text-checked / textChecked
string | undefined

The switch's checked text.

undefined
text-unchecked / textUnchecked
string | undefined

The switch's unchecked text.

undefined
validation-message / validationMessage
string

The error message that would be shown to the user if the <qds-switch> was to be checked for validity.

''
ValidityState

The ValidityState object for this <qds-switch>.

VALID_STATE
value
null | number | string | undefined

The value of the switch, submitted as a name/value pair with form data.

undefined
will-validate / willValidate
boolean

True if <qds-switch> will be validated when the form is submitted; false otherwise.

false

Events​

EventTypeDescriptionBubblesCancelableComposedqdsBlur
{ readonly relatedTarget: EventTarget | null; }

Emitted when the switch loses focus.

qdsChange
void

Emitted when a change to the switch's state is committed by the user.

qdsFocus
{ readonly relatedTarget: EventTarget | null; }

Emitted when the switch gains focus.

Last updated on