Description

An <sp-switch> is used to turn an option on or off. Switches allow users to select the state of a single option at a time. Use a switch rather than a checkbox when activating (or deactivating) an option, instead of selecting.

Usage

yarn add @spectrum-web-components/switch

Import the side effectful registration of <sp-switch> via:

import '@spectrum-web-components/switch/sp-switch.js';

When looking to leverage the Switch base class as a type and/or for extension purposes, do so via:

import { Switch } from '@spectrum-web-components/switch';

Example

<sp-switch label="Switch" onclick="spAlert(this, '<sp-switch> clicked!')">
    Switch
</sp-switch>

Standard switch buttons

Standard switches are the default style for switches. They are optimal for application panels where all visual elements are monochrome in order to direct focus to the content.

<div style="display: flex; justify-content: space-between;">
    <div style="display: flex; flex-direction: column;">
        <h4 class="spectrum-Heading--subtitle1">Default</h4>
        <sp-field-group selected="first" name="example" vertical>
            <sp-switch value="off">Switch Off</sp-switch>
            <sp-switch value="on" checked>Switch On</sp-switch>
        </sp-field-group>
    </div>

    <div style="display: flex; flex-direction: column;">
        <h4 class="spectrum-Heading--subtitle1">Disabled</h4>
        <sp-field-group selected="first" name="example" vertical>
            <sp-switch disabled value="off">Switch Off</sp-switch>
            <sp-switch disabled value="on" checked>Switch On</sp-switch>
        </sp-field-group>
    </div>
</div>

Sizes

<sp-switch size="s">Small</sp-switch>

<sp-switch size="m">Medium</sp-switch>

<sp-switch size="l">Large</sp-switch>

<sp-switch size="xl">Extra Large</sp-switch>

Emphasized radio buttons

Emphasized switches are a secondary style for switches. The blue color provides a visual prominence that is optimal for forms, settings, etc. where the switches need to be noticed.

<div style="display: flex; justify-content: space-between;">
    <div style="display: flex; flex-direction: column;">
        <h4 class="spectrum-Heading--subtitle1">Default</h4>
        <sp-field-group selected="first" name="example" vertical>
            <sp-switch emphasized value="off">Switch Off</sp-switch>
            <sp-switch emphasized value="on" checked>Switch On</sp-switch>
        </sp-field-group>
    </div>

    <div style="display: flex; flex-direction: column;">
        <h4 class="spectrum-Heading--subtitle1">Disabled</h4>
        <sp-field-group selected="first" name="example" vertical>
            <sp-switch emphasized disabled value="off">Switch Off</sp-switch>
            <sp-switch emphasized disabled value="on" checked>Switch On</sp-switch>
        </sp-field-group>
    </div>
</div>

Handling events

Event handlers for clicks and other user actions can be registered on an <sp-switch> similar to a standard <input type="checkbox"> element.

<sp-switch id="switch-example" onclick="spAlert(this, '<sp-radio> clicked!')">
    Web component
</sp-switch>

Accessibility

Switch are accessible by default, rendered in HTML using the <input type="checkbox"> element with the appropriate accessibility role, switch. When the Switch is checked or invalid, the appropriate ARIA state attribute will automatically be applied.