sp-switch

NPM 1.0.1

View Storybook

Try it on webcomponents.dev
Overview API Changelog

Overview

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';

Anatomy

A switch consists of a switch input and slotted label.

<sp-switch>Email notifications</sp-switch>

Checked

A switch can be checked by setting the checked property/attribute.

<sp-field-group vertical>
    <sp-switch>Not checked</sp-switch>
    <sp-switch checked>Checked</sp-switch>
</sp-field-group>

Options

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

Emphasized switches, which use the empahasized attribute/property 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.

<sp-field-group vertical>
    <sp-switch emphasized>Emphasized</sp-switch>
    <sp-switch emphasized checked>Emphasized and checked</sp-switch>
</sp-field-group>

States

A switch can be disabled using the disabled property/attribute.

<sp-field-group vertical>
    <sp-switch disabled>Disabled</sp-switch>
    <sp-switch disabled checked>Disabled and checked</sp-switch>
</sp-field-group>

Behaviors

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-switch> clicked!')">
    Web component
</sp-switch>

Accessibility

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

Include a label

A switch is required to have either a visible text label nested inside <sp-switch> itself.

<sp-switch>Email notifications</sp-switch>

Standalone switches should be used in situations where the context is clear without an associated text label. For example, a switch located at the top of a panel next to the panel's title makes it clear that the switch will enable/disable the panel options.

In those cases, you can use CSS to visually hide the text label.

<div id="settings">
    <sp-field-label for="notifications-settings">Notifications</sp-field-label>
    <sp-switch id="notify">
        <span class="visually-hidden">Notifications</span>
    </sp-switch>
    <sp-field-group id="notifications-settings" vertical>
        <sp-switch disabled>Email</sp-switch>
        <sp-switch disabled>Telephone</sp-switch>
        <sp-switch disabled>Text</sp-switch>
    </sp-field-group>
</div>

<style>
    .visually-hidden {
        clip: rect(0 0 0 0);
        clip-path: inset(50%);
        height: 1px;
        overflow: hidden;
        position: absolute;
        white-space: nowrap;
        width: 1px;
    }
    #settings {
        display: grid;
        grid-gap: 10px;
        grid-template-columns: calc(100% - 50px) 50px;
    }
    #notifications-settings {
        grid-column: 1 / 3;
        grid-row: 2;
    }
</style>

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 provides an alternate style that is meant to be noticed 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

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/switch

1.0.0 (2024-10-31)

Note: Version bump only for package @spectrum-web-components/switch

0.49.0 (2024-10-15)

Note: Version bump only for package @spectrum-web-components/switch

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/switch

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/switch

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/switch

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/switch

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/switch

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/switch

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/switch

0.44.0 (2024-07-15)

Note: Version bump only for package @spectrum-web-components/switch

0.43.0 (2024-06-11)

Note: Version bump only for package @spectrum-web-components/switch

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/switch

0.42.4 (2024-05-14)

Note: Version bump only for package @spectrum-web-components/switch

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/switch

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/switch

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/switch

0.42.0 (2024-03-19)

Features

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/switch

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/switch

0.41.0 (2024-02-13)

Note: Version bump only for package @spectrum-web-components/switch

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/switch

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/switch

0.40.3 (2024-01-11)

Note: Version bump only for package @spectrum-web-components/switch

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/switch

0.40.1 (2023-12-05)

Performance Improvements

  • checkbox: refactor architecture for more rendering perf and DOM element count (7c2277f)

0.40.0 (2023-11-16)

Features

  • textfield: added name attribute to textfield (#3752) (593005a)

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/switch

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/switch

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/switch

0.39.1 (2023-10-06)

Note: Version bump only for package @spectrum-web-components/switch

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/switch

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/switch

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/switch

0.36.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/switch

0.35.0 (2023-07-31)

Note: Version bump only for package @spectrum-web-components/switch

0.34.0 (2023-07-11)

Note: Version bump only for package @spectrum-web-components/switch

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/switch

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/switch

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/switch

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/switch

0.30.0 (2023-05-03)

Bug Fixes

  • add support for "readonly" attribute (4bce3b7)
  • correct @element jsDoc listing across library (c97a632)
  • ensure [disabled] styling (4c067eb)
  • ensure aria attributes based on state (6ee43de)
  • focusable style (48ea3e7)
  • implement "emphasized" styles (750bbe7)
  • include "type" in package.json, generate custom-elements.json (1a8d716)
  • include default export in the "exports" fields (f32407d)
  • include the "types" entry in package.json files (b432f59)
  • move hover/focus hoisting into conditioning (15ac2f7)
  • stop merging selectors in a way that alters the cascade (369388f)
  • switch: process CSS correction (292fff1)
  • switch: track aria-checked (1980046)
  • update configuration for Spectrum CSS processing for specificity (5c2e21e)
  • update latest Spectrum CSS beta releases (d8d3acc)
  • update side effect listings (8160d3a)
  • update to latest spectrum-css packages (a5ca19f)
  • workaround bug in Edge with switches (7014a2c)

Features

  • action-button: add action button pattern (03ac00a)
  • action-group: add action-group pattern (d2de766)
  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • include all Dev Mode files in side effects (f70817c)
  • leverage "exports" field in package.json (321abd7)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • switch: update spectrum css input (1d2ce17)
  • switch: use core tokens (8011ead)
  • update to Spectrum CSS v3.0.0 (e8b3d8f)
  • use :focus-visable (via polyfill) instead of :focus (11c6fc7)
  • use @adobe/spectrum-css@2.15.1 (3918888)
  • use latest exports specification (a7ecf4b)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)
  • use imported TypeScript helpers instead of inlining them (cc2bd0a)

Reverts

  • Revert "chore: release new versions" (a6d655d)

0.11.13 (2023-04-24)

Note: Version bump only for package @spectrum-web-components/switch

0.11.12 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/switch

0.11.11 (2023-03-22)

Bug Fixes

  • move hover/focus hoisting into conditioning (15ac2f7)

0.11.10 (2023-03-08)

Note: Version bump only for package @spectrum-web-components/switch

0.11.9 (2023-02-23)

Note: Version bump only for package @spectrum-web-components/switch

0.11.8 (2023-02-08)

Note: Version bump only for package @spectrum-web-components/switch

0.11.7 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/switch

0.11.6 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/switch

0.11.5 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/switch

0.11.4 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/switch

0.11.3 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/switch

0.11.2 (2022-10-28)

Note: Version bump only for package @spectrum-web-components/switch

0.11.1 (2022-10-17)

Note: Version bump only for package @spectrum-web-components/switch

0.11.0 (2022-10-10)

Features

  • switch: use core tokens (8011ead)

0.10.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.9.14 (2022-08-04)

Note: Version bump only for package @spectrum-web-components/switch

0.9.13 (2022-07-18)

Note: Version bump only for package @spectrum-web-components/switch

0.9.12 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/switch

0.9.11 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/switch

0.9.10 (2022-05-27)

Note: Version bump only for package @spectrum-web-components/switch

0.9.9 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/switch

0.9.8 (2022-04-21)

Note: Version bump only for package @spectrum-web-components/switch

0.9.7 (2022-03-30)

Note: Version bump only for package @spectrum-web-components/switch

0.9.6 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/switch

0.9.5 (2022-03-04)

Note: Version bump only for package @spectrum-web-components/switch

0.9.4 (2022-02-22)

Note: Version bump only for package @spectrum-web-components/switch

0.9.3 (2022-01-26)

Note: Version bump only for package @spectrum-web-components/switch

0.9.2 (2022-01-07)

Note: Version bump only for package @spectrum-web-components/switch

0.9.1 (2021-12-13)

Note: Version bump only for package @spectrum-web-components/switch

0.9.0 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/switch

0.8.1 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/switch

0.8.0 (2021-11-02)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.7.16 (2021-10-12)

Note: Version bump only for package @spectrum-web-components/switch

0.7.15 (2021-09-20)

Note: Version bump only for package @spectrum-web-components/switch

0.7.14 (2021-09-13)

Note: Version bump only for package @spectrum-web-components/switch

0.7.13 (2021-08-24)

Bug Fixes

  • correct @element jsDoc listing across library (c97a632)

0.7.12 (2021-08-03)

Note: Version bump only for package @spectrum-web-components/switch

0.7.11 (2021-07-22)

Note: Version bump only for package @spectrum-web-components/switch

0.7.10 (2021-07-01)

Note: Version bump only for package @spectrum-web-components/switch

0.7.9 (2021-06-16)

Note: Version bump only for package @spectrum-web-components/switch

0.7.8 (2021-06-07)

Note: Version bump only for package @spectrum-web-components/switch

0.7.7 (2021-05-24)

Note: Version bump only for package @spectrum-web-components/switch

0.7.6 (2021-05-12)

Note: Version bump only for package @spectrum-web-components/switch

0.7.5 (2021-04-09)

Note: Version bump only for package @spectrum-web-components/switch

0.7.4 (2021-03-29)

Note: Version bump only for package @spectrum-web-components/switch

0.7.3 (2021-03-22)

Note: Version bump only for package @spectrum-web-components/switch

0.7.2 (2021-03-22)

Bug Fixes

  • add support for "readonly" attribute (4bce3b7)

0.7.1 (2021-03-05)

Note: Version bump only for package @spectrum-web-components/switch

0.7.0 (2021-03-04)

Features

  • use latest exports specification (a7ecf4b)

0.6.3 (2021-02-11)

Bug Fixes

  • update to latest spectrum-css packages (a5ca19f)

0.6.2 (2021-02-02)

Note: Version bump only for package @spectrum-web-components/switch

0.6.1 (2021-01-28)

Note: Version bump only for package @spectrum-web-components/switch

0.6.0 (2021-01-21)

Bug Fixes

  • ensure [disabled] styling (4c067eb)
  • implement "emphasized" styles (750bbe7)
  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update configuration for Spectrum CSS processing for specificity (5c2e21e)
  • update latest Spectrum CSS beta releases (d8d3acc)

Features

  • action-button: add action button pattern (03ac00a)
  • switch: update spectrum css input (1d2ce17)

0.5.0 (2021-01-13)

Bug Fixes

  • implement "emphasized" styles (750bbe7)
  • include the "types" entry in package.json files (b432f59)
  • stop merging selectors in a way that alters the cascade (369388f)
  • update latest Spectrum CSS beta releases (d8d3acc)

Features

  • action-button: add action button pattern (03ac00a)
  • switch: update spectrum css input (1d2ce17)

0.4.4 (2020-10-12)

Note: Version bump only for package @spectrum-web-components/switch

0.4.3 (2020-10-12)

Bug Fixes

  • include default export in the "exports" fields (f32407d)

0.4.2 (2020-09-25)

Bug Fixes

  • update side effect listings (8160d3a)

0.4.1 (2020-09-14)

Note: Version bump only for package @spectrum-web-components/switch

0.4.0 (2020-08-31)

Features

  • update to Spectrum CSS v3.0.0 (e8b3d8f)
  • action-group: add action-group pattern (d2de766)

0.3.4 (2020-08-19)

Note: Version bump only for package @spectrum-web-components/switch

0.3.3 (2020-07-27)

Note: Version bump only for package @spectrum-web-components/switch

0.3.2 (2020-07-24)

Note: Version bump only for package @spectrum-web-components/switch

0.3.1 (2020-07-22)

Note: Version bump only for package @spectrum-web-components/switch

0.3.0 (2020-07-17)

Bug Fixes

  • switch: track aria-checked (1980046)

Features

  • leverage "exports" field in package.json (321abd7)

0.2.16 (2020-06-08)

Note: Version bump only for package @spectrum-web-components/switch

0.2.15 (2020-05-08)

Bug Fixes

  • switch: process CSS correction (292fff1)
  • ensure aria attributes based on state (6ee43de)

0.2.14 (2020-04-21)

Bug Fixes

  • workaround bug in Edge with switches (7014a2c)

0.2.13 (2020-04-16)

Performance Improvements

  • use "sideEffects" listing in package.json (7271614)

0.2.12 (2020-04-10)

Note: Version bump only for package @spectrum-web-components/switch

0.2.11 (2020-04-07)

Note: Version bump only for package @spectrum-web-components/switch

0.2.10 (2020-03-11)

Note: Version bump only for package @spectrum-web-components/switch

0.2.9 (2020-02-05)

Note: Version bump only for package @spectrum-web-components/switch

0.2.8 (2020-02-01)

Note: Version bump only for package @spectrum-web-components/switch

0.2.7 (2020-01-30)

Note: Version bump only for package @spectrum-web-components/switch

0.2.6 (2020-01-06)

Note: Version bump only for package @spectrum-web-components/switch

0.2.5 (2019-12-12)

Note: Version bump only for package @spectrum-web-components/switch

0.2.4 (2019-12-09)

Note: Version bump only for package @spectrum-web-components/switch

0.2.3 (2019-12-03)

Bug Fixes

  • focusable style (48ea3e7)

0.2.2 (2019-12-02)

Note: Version bump only for package @spectrum-web-components/switch

0.2.1 (2019-11-27)

Bug Fixes

  • include "type" in package.json, generate custom-elements.json (1a8d716)

0.2.0 (2019-11-19)

Features

  • use :focus-visable (via polyfill) instead of :focus (11c6fc7)
  • use @adobe/spectrum-css@2.15.1 (3918888)

0.1.5 (2019-11-01)

Note: Version bump only for package @spectrum-web-components/switch

0.1.4 (2019-10-14)

Performance Improvements

  • use imported TypeScript helpers instead of inlining them (cc2bd0a)

0.1.3 (2019-10-03)

Note: Version bump only for package @spectrum-web-components/switch