sp-switch

Examples API

Attributes and Properties #

Property Attribute Type Default Description
autofocus autofocus boolean false When this control is rendered, focus it automatically
checked checked boolean false
dir dir 'ltr' | 'rtl' 'ltr'
disabled disabled boolean false Disable this control. It will not receive focus or events
emphasized emphasized boolean false
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

CSS Custom Properties #

Name Default
--spectrum-alias-focus-ring-gap var(--spectrum-global-dimension-static-size-25)
--spectrum-switch-m-cursor-hit-x var(--spectrum-global-dimension-size-100)
--spectrum-switch-m-emphasized-handle-border-color-selected var(--spectrum-alias-toggle-background-color-emphasized-selected-default)
--spectrum-switch-m-emphasized-handle-border-color-selected-down var(--spectrum-alias-toggle-background-color-emphasized-selected-down)
--spectrum-switch-m-emphasized-handle-border-color-selected-hover var(--spectrum-alias-toggle-background-color-emphasized-selected-hover)
--spectrum-switch-m-emphasized-handle-border-color-selected-key-focus var(--spectrum-alias-toggle-background-color-emphasized-selected-key-focus)
--spectrum-switch-m-emphasized-track-color-selected var(--spectrum-alias-toggle-background-color-emphasized-selected-default)
--spectrum-switch-m-emphasized-track-color-selected-down var(--spectrum-alias-toggle-background-color-emphasized-selected-down)
--spectrum-switch-m-emphasized-track-color-selected-hover var(--spectrum-alias-toggle-background-color-emphasized-selected-hover)
--spectrum-switch-m-emphasized-track-color-selected-key-focus var(--spectrum-alias-toggle-background-color-emphasized-selected-key-focus)
--spectrum-switch-m-focus-ring-color-key-focus var(--spectrum-alias-focus-ring-color)
--spectrum-switch-m-focus-ring-size var(--spectrum-alias-focus-ring-size)
--spectrum-switch-m-handle-background-color var(--spectrum-global-color-gray-75)
--spectrum-switch-m-handle-border-color var(--spectrum-alias-toggle-border-color-default)
--spectrum-switch-m-handle-border-color-disabled var(--spectrum-global-color-gray-400)
--spectrum-switch-m-handle-border-color-down var(--spectrum-alias-toggle-border-color-down)
--spectrum-switch-m-handle-border-color-hover var(--spectrum-alias-toggle-border-color-hover)
--spectrum-switch-m-handle-border-color-key-focus var(--spectrum-alias-toggle-border-color-key-focus)
--spectrum-switch-m-handle-border-color-selected var(--spectrum-alias-toggle-background-color-default)
--spectrum-switch-m-handle-border-color-selected-disabled var(--spectrum-global-color-gray-400)
--spectrum-switch-m-handle-border-color-selected-down var(--spectrum-alias-toggle-background-color-down)
--spectrum-switch-m-handle-border-color-selected-hover var(--spectrum-alias-toggle-background-color-hover)
--spectrum-switch-m-handle-border-color-selected-key-focus var(--spectrum-alias-toggle-background-color-key-focus)
--spectrum-switch-m-handle-border-radius var(--spectrum-alias-control-two-border-radius-m)
--spectrum-switch-m-handle-border-size var(--spectrum-alias-border-size-thick)
--spectrum-switch-m-handle-size var(--spectrum-alias-control-two-size-m)
--spectrum-switch-m-height var(--spectrum-global-dimension-size-400)
--spectrum-switch-m-text-color var(--spectrum-alias-component-text-color-default)
--spectrum-switch-m-text-color-disabled var(--spectrum-alias-component-text-color-disabled)
--spectrum-switch-m-text-color-down var(--spectrum-alias-component-text-color-down)
--spectrum-switch-m-text-color-hover var(--spectrum-alias-component-text-color-hover)
--spectrum-switch-m-text-color-selected-disabled var(--spectrum-alias-component-text-color-disabled)
--spectrum-switch-m-text-gap var(--spectrum-global-dimension-size-125)
--spectrum-switch-m-text-size var(--spectrum-global-dimension-font-size-100)
--spectrum-switch-m-track-color var(--spectrum-global-color-gray-300)
--spectrum-switch-m-track-color-disabled var(--spectrum-global-color-gray-300)
--spectrum-switch-m-track-color-selected var(--spectrum-alias-toggle-background-color-default)
--spectrum-switch-m-track-color-selected-disabled var(--spectrum-global-color-gray-400)
--spectrum-switch-m-track-color-selected-down var(--spectrum-alias-toggle-background-color-down)
--spectrum-switch-m-track-color-selected-hover var(--spectrum-alias-toggle-background-color-hover)
--spectrum-switch-m-track-color-selected-key-focus var(--spectrum-alias-toggle-background-color-key-focus)
--spectrum-switch-m-track-height var(--spectrum-alias-control-three-height-m)
--spectrum-switch-m-track-width var(--spectrum-alias-control-three-width-m)

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 radio 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>

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.