sp-switch

NPM 1.12.0

View Storybook

Try it on Stackblitz
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 Stackblitz

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

Minor Changes

  • #6097 f842573 Thanks @marissahuysentruyt! - - Fixed: Improved <sp-switch> contrast in S1 and Express to meet WCAG SC 1.4.11 Non-text Contrast (3:1 minimum). The unselected track border was added in S1 and Express, matching the S2 pattern of matching the handle background color to the track border color per interaction state.

    • Fixed: Corrected <sp-switch> handle border colors for selected states in S1 and Express. Handle border now resolves to --spectrum-gray-75 against the filled/selected track background.
    • Fixed: Improved <sp-switch> Forced Colors (Windows High Contrast) mode. Replaced box-shadow track borders with proper border declarations, expanded --highcontrast-switch-border-color to full state-specific tokens (default, hover, focus, down, disabled), and corrected handle border colors to use system colors (ButtonFace for selected, GrayText for disabled).
    • Changed: Renamed --spectrum-switch-border-width-themed to --spectrum-switch-border-width on <sp-switch>. The border width is now a consistent 2px in all themes. The --mod-switch-border-width-themed variable remains unaffected.
    • Changed: Renamed --highcontrast-switch-border-color to --highcontrast-switch-border-color-default on <sp-switch>, and expanded it to full per-state tokens (hover, focus, down, disabled). Previously a single token controlled the track border color in all forced-colors states.

    If you were overriding --highcontrast-switch-border-color in Windows High Contrast styles, update your usage to the appropriate state-specific token.

    /* Before */
sp-switch {
  --highcontrast-switch-border-color: Highlight;
}

/* After */
sp-switch {
  --highcontrast-switch-border-color-default: Highlight;
}

Patch Changes

  • #6065 52947c8 Thanks @marissahuysentruyt! - Added: New switch component tokens and styles were mapped to bring more fidelity for Spectrum 2 foundations theme. Switch now uses system theme tokens for track and handle border colors, handle background, and themed border width; S1 and Express handle border colors are preserved. Users can hook into --mod-switch-border-width-themed to adjust the switch input border; --mod-switch-border-color-* to modify the switch input border color; --mod-switch-handle-border-color-* to change the handle/thumb border color.

    Fixed: S2 foundations switch emphasized down state color was fixed to reflect the S2 switch down state design spec. The high contrast input border color for S2, and a high-contrast typo are fixed.

    Fixed: Theme bridge token additions and updates in @spectrum-web-components/styles (Spectrum, Express, and tokens-v2) support the switch overrides.

  • Updated dependencies [ba14a2b, dc6a8e8, f37dec6]:

    • @spectrum-web-components/base@1.12.0
    • @spectrum-web-components/checkbox@1.12.0

1.11.2

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.11.2
    • @spectrum-web-components/checkbox@1.11.2

1.11.1

Patch Changes

  • Updated dependencies [95e1c25]:
    • @spectrum-web-components/base@1.11.1
    • @spectrum-web-components/checkbox@1.11.1

1.11.0

Patch Changes

  • Updated dependencies [9cb816b]:
    • @spectrum-web-components/base@1.11.0
    • @spectrum-web-components/checkbox@1.11.0

1.10.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.10.0
    • @spectrum-web-components/checkbox@1.10.0

1.9.1

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/checkbox@1.9.1
    • @spectrum-web-components/base@1.9.1

1.9.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/checkbox@1.9.0
    • @spectrum-web-components/base@1.9.0

1.8.0

Patch Changes

  • #5524 dcd2cd3 Thanks @marissahuysentruyt! - ### Fix down state colors for switch

    Because the postcss-hover-media-feature plugin converts hover styles into a media query for devices that support hover, the hover styles were overriding any active/down state styles. We needed to target the active/down states of the switch with additional active state selectors, in order to ensure that the active state takes precedence over the hover state, maintaining the correct visual behavior of the switch component across different interaction states.

    This fix should address hover + active state discrepancies in S1 and S2 foundations.

  • Updated dependencies []:

    • @spectrum-web-components/checkbox@1.8.0
    • @spectrum-web-components/base@1.8.0

1.7.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/checkbox@1.7.0
    • @spectrum-web-components/base@1.7.0

1.6.0

Patch Changes

  • #5349 a9727d2 Thanks @renovate! - Remove unnecessary system theme references to reduce complexity for components that don't need the additional mapping layer.

  • Updated dependencies []:

    • @spectrum-web-components/checkbox@1.6.0
    • @spectrum-web-components/base@1.6.0

1.5.0

Patch Changes

  • Updated dependencies [a4de4c7]:
    • @spectrum-web-components/checkbox@1.5.0
    • @spectrum-web-components/base@1.5.0

1.4.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/checkbox@1.4.0
    • @spectrum-web-components/base@1.4.0

1.3.0

Patch Changes

  • Updated dependencies [468314f]:
    • @spectrum-web-components/checkbox@1.3.0
    • @spectrum-web-components/base@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.2.0 (2025-02-27)

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

1.1.2 (2025-02-12)

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

1.1.1 (2025-01-29)

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

1.1.0 (2025-01-29)

Bug Fixes

  • lock prerelease versions for Spectrum CSS (#5014) (8aa7734)

1.0.3 (2024-12-09)

Note: Version bump only for package @spectrum-web-components/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

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