sp-switch

NPM

0.42.2

Spectrum

View guidelines

Storybook

View Storybook

Try it on

webcomponents.dev
Examples API

Attributes and Properties #

Property Attribute Type Default Description checked checked boolean false disabled disabled boolean false Disable this control. It will not receive focus or events emphasized emphasized boolean false name name string | undefined readonly readonly boolean false tabIndex tabIndex number The tab index to apply to this control. See general documentation about the tabindex HTML property

Slots #

Name Description default slot text label of the Switch

Events #

Name Type Description change Event Announces a change in the `checked` property of a Switch

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 #

See it on NPM! How big is this package in your project? Try it on webcomponents.dev

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 #

Small 
<sp-switch size="s">Small</sp-switch>
 Medium 
<sp-switch size="m">Medium</sp-switch>
 Large 
<sp-switch size="l">Large</sp-switch>
 Extra Large 
<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.