sp-theme

Deprecation Warning
Color 'lightest' and 'darkest' are deprecated. The 'theme' attribute has been deprecated in favor of 'system'. These deprecations will be removed in a future release.

NPM 1.9.0
Overview API Changelog

Overview

<sp-theme> provides Spectrum design tokens (CSS custom properties) to everything in its DOM scope. Components inside a theme use these tokens to render correctly. The element itself does not visually “apply” styles to your app; it exposes the tokens so your components (and any of your CSS) can consume them.

Spectrum offers multiple variants:

  • System: spectrum, express, spectrum-two
  • Color: light, dark (legacy: lightest, darkest – deprecated)
  • Scale: medium, large

Usage

See it on NPM! How big is this package in your project?

yarn add @spectrum-web-components/theme

Register the element and load the theme fragments you intend to use:

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

// Load the specific variants you will use (recommended)
import '@spectrum-web-components/theme/theme-light.js';
import '@spectrum-web-components/theme/scale-medium.js';
// Optionally choose a different system
// import '@spectrum-web-components/theme/express/theme-light.js';
// import '@spectrum-web-components/theme/express/scale-medium.js';

If you’re prototyping and want everything available:

import '@spectrum-web-components/theme/sp-theme.js';
import '@spectrum-web-components/theme/src/themes.js'; // spectrum
import '@spectrum-web-components/theme/src/express/themes.js'; // express
import '@spectrum-web-components/theme/src/spectrum-two/themes.js'; // spectrum-two

Examples

Light theme, medium scale

<style type="text/css">
    #outer {
        max-width: 500px;
        padding: 1em;
        background-color: var(--spectrum-gray-100);
        color: var(--spectrum-gray-800);
    }
</style>
<sp-theme system="spectrum" color="light" scale="medium">
    <div id="outer">
        <sp-field-label for="email">Email</sp-field-label>
        <sp-textfield
            id="email"
            type="email"
            placeholder="you@example.com"
        ></sp-textfield>
        <sp-help-text>We’ll only use this to send a receipt.</sp-help-text>
        <sp-button-group style="margin-top: var(--spectrum-spacing-400)">
            <sp-button variant="primary">Submit</sp-button>
            <sp-button variant="secondary">Cancel</sp-button>
        </sp-button-group>
    </div>
</sp-theme>

Dark theme, large scale

The large scale of <sp-theme> will switch to using Spectrum's larger mobile Platform Scale.

<style type="text/css">
    #outer {
        max-width: 500px;
        padding: 1em;
        background-color: var(--spectrum-gray-100);
        color: var(--spectrum-gray-800);
    }
</style>
<sp-theme system="spectrum" color="dark" scale="large">
    <div id="outer">
        <sp-field-label for="volume">Volume</sp-field-label>
        <sp-slider id="volume" label="Volume" value="50"></sp-slider>
        <sp-switch>Overdrive</sp-switch>
    </div>
</sp-theme>

Embedded themes and directional content

There are a few cases where it is necessary to embed one theme within another. For example, if you have an application that is using a dark theme with a left to right text direction that is previewing or editing content that will be displayed in a light theme with a right to left text direction.

<style type="text/css">
    #outer {
        max-width: 500px;
        padding: 1em;
        background-color: var(--spectrum-gray-100);
        color: var(--spectrum-gray-800);
    }

    #inner {
        margin-top: 2em;
        padding: 1em;
        background-color: var(--spectrum-gray-100);
        color: var(--spectrum-gray-800);
    }

    #buttons {
        margin-top: 2em;
    }
</style>
<sp-theme color="dark" dir="ltr">
    <div id="outer">
        <div>
            <sp-slider
                value="5"
                step="1"
                min="1"
                max="11"
                label="Volume"
                id="volume-slider"
            ></sp-slider>
        </div>
        <div><sp-switch>Overdrive</sp-switch></div>
        <sp-button-group id="buttons">
            <sp-button variant="primary">Cancel</sp-button>
            <sp-button variant="accent">Continue</sp-button>
        </sp-button-group>
        <sp-theme color="light" dir="rtl">
            <div id="inner">
                <div>
                    <sp-slider
                        value="5"
                        step="1"
                        min="1"
                        max="11"
                        label="Volume"
                        id="volume-slider"
                    ></sp-slider>
                </div>
                <div><sp-switch>Overdrive</sp-switch></div>
                <sp-button-group id="buttons">
                    <sp-button variant="primary">Cancel</sp-button>
                    <sp-button variant="accent">Continue</sp-button>
                </sp-button-group>
            </div>
        </sp-theme>
    </div>
</sp-theme>

Advanced usage

What it does

Visually, all Spectrum Web Components are an expression of the design tokens specified by Spectrum, Adobe's design system. On the web, these tokens are made available as CSS Custom Properties. Using sp-theme as a parent element for your components ensures that those CSS Custom Properties can be leveraged by the elements within your application. This ensures consistent delivery of not only the color and scale you've specified in your particular instance, but for all the other color, scale, and content direction specifications across Spectrum.

Additionally, the sp-theme element manages the content direction applied to the elements in its DOM scope. By default, an sp-theme element resolves its initial content direction from the value specified by its first sp-theme or document ancestor; otherwise, it uses the value dir="ltr" if a content direction isn't present in those elements. When a value for dir is manually supplied to sp-theme, the default value is overridden. In all cases, though, sp-theme manages the dir value of its SpectrumElement descendents, unless another sp-theme element is placed into its scope and overrides that management.

To make the above concepts a little more concrete, take a look at the table below. Try selecting another color in the picker, and notice how that changes the values of the colors. The token names for the variables persist, but the RGB values under the hood change! Considering that sp-theme also manages all the other theme and size options, sp-theme reveals itself to be a pretty powerful component.

When you're ready to look into more advanced usage of the components and themes in your application, there are vanilla CSS implementations of these tokens available in the @spectrum-web-components/styles package.

Lazy loading themes

Load only what you need by importing the specific fragments, then lazy-load others as your user changes theme settings.

const themeEl = document.querySelector('sp-theme');

async function updateTheme(system, color, scale) {
    const systemBase = system === 'spectrum' ? '' : `${system}/`;
    await Promise.all([
        import(`@spectrum-web-components/theme/${systemBase}theme-${color}.js`),
        import(`@spectrum-web-components/theme/${systemBase}scale-${scale}.js`),
    ]);
    themeEl.system = system;
    themeEl.color = color;
    themeEl.scale = scale;
}

updateTheme('spectrum', 'light', 'medium');

When bundling your application, be sure to consult the documentation of your bundler for the correct way to ensure proper packaging of the programatic dependency graph that this will create.

Language context

Descendants can request the current language by dispatching sp-language-context with a callback. The callback is re-invoked when the theme’s lang changes. This way, you can control the resolved language in <sp-number-field>, <sp-slider>, and other elements in one centralized place.

// in a descendant component
this.dispatchEvent(
    new CustomEvent('sp-language-context', {
        bubbles: true,
        composed: true,
        detail: {
            callback: (lang, unsubscribe) => {
                this.lang = lang; // use the language value
                // call unsubscribe() when you no longer need updates
            },
        },
    })
);

Accessibility

  • Color and contrast: Ensure sufficient contrast for any backgrounds you apply when consuming tokens (WCAG 2.1 AA). Components themselves meet Spectrum guidance when themed correctly.
  • Language: Set lang on <sp-theme> to inform number/date formatting and other locale-aware components.
  • Directionality: Use dir to deliver correct LTR/RTL behavior; embedded themes allow mixing contexts.

Slots

Name Description default slot Content on which to apply the CSS Custom Properties defined by the current theme configuration

Patch Changes

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

1.8.0

Patch Changes

  • Updated dependencies [77bdef6, 15be17d]:
    • @spectrum-web-components/styles@1.8.0
    • @spectrum-web-components/base@1.8.0

1.7.0

Patch Changes

  • Updated dependencies [1126cf2]:
    • @spectrum-web-components/styles@1.7.0
    • @spectrum-web-components/base@1.7.0

1.6.0

Patch Changes

  • Updated dependencies [9e15a66, a9727d2]:
    • @spectrum-web-components/styles@1.6.0
    • @spectrum-web-components/base@1.6.0

1.5.0

Patch Changes

  • Updated dependencies [165a904, 4e06533, fa4be70, daeb11f, 6c58f50, fa4be70]:
    • @spectrum-web-components/styles@1.5.0
    • @spectrum-web-components/base@1.5.0

1.4.0

Patch Changes

  • Updated dependencies [3cca7ea]:
    • @spectrum-web-components/styles@1.4.0
    • @spectrum-web-components/base@1.4.0

1.3.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.3.0
    • @spectrum-web-components/styles@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/theme

1.1.2 (2025-02-12)

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

1.1.1 (2025-01-29)

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

1.1.0 (2025-01-29)

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

1.0.3 (2024-12-09)

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

1.0.1 (2024-11-11)

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

1.0.0 (2024-10-31)

BREAKING CHANGES

  • remove 'theme' attribute from sp-theme (#4765)

0.49.0 (2024-10-15)

Features

  • add static-color to replace static (#4808) (43cf086)

0.48.1 (2024-10-01)

Bug Fixes

  • add file extension to Theme imports and respective eslint rule (#4771) (a2b6bea)

0.48.0 (2024-09-17)

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

0.47.2 (2024-09-03)

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

0.47.1 (2024-08-27)

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

0.47.0 (2024-08-20)

Features

  • breadcrumbs: add Breadcrumbs component (#4578) (acd4b5e)

0.46.0 (2024-08-08)

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

0.45.0 (2024-07-30)

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

0.44.0 (2024-07-15)

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

0.43.0 (2024-06-11)

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

0.42.5 (2024-05-24)

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

0.42.4 (2024-05-14)

Bug Fixes

  • styles,theme: add S2 tokens and theme (#4241) (a29e4a2), closes #4232 #4228
  • theme: deprecate theme property for system (#4230) (ac26168)

0.42.3 (2024-05-01)

Bug Fixes

  • theme: deprecate theme property for system (#4230) (ac26168)

0.42.2 (2024-04-03)

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

0.42.1 (2024-04-02)

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

0.42.0 (2024-03-19)

Bug Fixes

  • styles, theme: surface exports that omit Spectrum Vars proactively (#4142) (5b524c1)
  • theme: deprecate lightest and darkest color stops (#4179) (0c01a66)

0.41.2 (2024-03-05)

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

0.41.1 (2024-02-22)

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

0.41.0 (2024-02-13)

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

0.40.5 (2024-02-05)

Bug Fixes

  • theme: expose version property (#3978) (d42bb71)
  • theme: include custom Spectrum color tokens in Express color tokens (370a1f1)

0.40.4 (2024-01-29)

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

0.40.3 (2024-01-11)

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

0.40.2 (2023-12-18)

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

0.40.1 (2023-12-05)

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

0.40.0 (2023-11-16)

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

0.39.4 (2023-11-02)

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

0.39.3 (2023-10-18)

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

0.39.2 (2023-10-13)

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

0.39.1 (2023-10-06)

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

0.39.0 (2023-09-25)

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

0.38.0 (2023-09-05)

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

0.37.0 (2023-08-18)

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

0.36.0 (2023-08-18)

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

0.35.0 (2023-07-31)

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

0.34.0 (2023-07-11)

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

0.33.2 (2023-06-14)

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

0.33.0 (2023-06-08)

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

0.32.0 (2023-06-01)

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

0.31.0 (2023-05-17)

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

0.30.0 (2023-05-03)

Bug Fixes

  • theme: stop language resolution propagation and demo using local languages (6b81391)

Features

  • styles: update typography to leverage Core Tokens (2f86560)

0.15.0 (2023-04-24)

Features

  • styles: update typography to leverage Core Tokens (2f86560)

0.14.14 (2023-04-05)

Bug Fixes

  • theme: stop language resolution propagation and demo using local languages (6b81391)

0.14.13 (2023-03-22)

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

0.14.12 (2023-03-08)

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

0.14.11 (2023-02-08)

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

0.14.10 (2023-01-23)

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

0.14.9 (2023-01-09)

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

0.14.8 (2022-12-08)

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

0.14.7 (2022-11-21)

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

0.14.6 (2022-11-14)

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

0.14.5 (2022-10-28)

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

0.14.4 (2022-10-17)

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

0.14.3 (2022-10-10)

Bug Fixes

  • convert the langage resolution workflow to a Reactive Controller (b7781db)
  • correct theme calculation for triggering warnings (5576329)

0.14.2 (2022-09-14)

Bug Fixes

  • add docs and address PR comments (568062a)

0.14.1 (2022-08-24)

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

0.14.0 (2022-08-09)

Features

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

0.13.0 (2022-08-04)

Features

  • delivery dev mode messages in various packages (62370a1)

0.12.0 (2022-07-18)

Features

  • support Spectrum Token consumption and update Action Button to use them (743ab16)

0.11.3 (2022-06-29)

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

0.11.2 (2022-06-07)

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

0.11.1 (2022-05-12)

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

0.11.0 (2022-04-21)

Bug Fixes

  • ensure all theme data is exported and listed for side effects (14efdc7)

Features

  • add support for Spectrum Express (12bfe99)

0.10.2 (2022-03-30)

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

0.10.1 (2022-03-08)

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

0.10.0 (2022-03-04)

Features

  • leverage latest Spectrum button API (9caf2f6)

0.9.4 (2022-02-22)

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

0.9.3 (2022-01-26)

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

0.9.2 (2022-01-07)

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

0.9.1 (2021-12-13)

Bug Fixes

  • use local declaration of ShadowRoot.adoptedStyleSheets (43f1c63)

0.9.0 (2021-11-08)

Features

  • update lit-* dependencies, wip (377f3c8)

0.8.16 (2021-11-08)

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

0.8.15 (2021-11-02)

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

0.8.14 (2021-09-20)

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

0.8.13 (2021-08-24)

Bug Fixes

  • correct @element jsDoc listing across library (c97a632)

0.8.12 (2021-08-03)

Bug Fixes

  • resolve "updateComplete" with a boolean like LitElement (2ebcd44)

0.8.11 (2021-07-22)

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

0.8.10 (2021-07-01)

Bug Fixes

  • manage "lang" via context provided by "sp-theme" (b1e3457)

0.8.9 (2021-06-16)

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

0.8.8 (2021-06-07)

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

0.8.7 (2021-05-12)

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

0.8.6 (2021-04-15)

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

0.8.5 (2021-04-09)

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

0.8.4 (2021-03-29)

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

0.8.3 (2021-03-22)

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

0.8.2 (2021-03-22)

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

0.8.1 (2021-03-05)

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

0.8.0 (2021-03-04)

Features

  • use latest exports specification (a7ecf4b)

0.7.4 (2021-02-11)

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

0.7.3 (2021-02-02)

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

0.7.2 (2021-01-28)

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

0.7.1 (2021-01-21)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • use latest @spectrum-css/* versions (c35eb86)

0.7.0 (2021-01-13)

Bug Fixes

  • include the "types" entry in package.json files (b432f59)
  • use latest @spectrum-css/* versions (c35eb86)

0.6.3 (2020-10-12)

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

0.6.2 (2020-10-12)

Bug Fixes

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

0.6.1 (2020-09-25)

Bug Fixes

  • update side effect listings (8160d3a)

0.6.0 (2020-08-31)

Features

  • allow dir management by sp-theme elements (2d10158)

0.5.2 (2020-07-24)

Bug Fixes

  • ensure browser understandable extensions (f4e59f7)

0.5.1 (2020-07-22)

Bug Fixes

  • theme: Use correct filename in exports field (d5da506)

0.5.0 (2020-07-17)

Features

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

0.4.1 (2020-06-08)

Bug Fixes

  • theme: prevent property sets attribute set property stack overflow (28d8a07)
  • theme: support lazily loading theme fragments (3c3b634)

0.4.0 (2020-04-16)

Bug Fixes

  • ensure themes are registered before adopting (a7ffb84)

Features

  • rule: add Spectrum rule pattern and apply to docs (f4c52ae)

Performance Improvements

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

0.3.2 (2020-04-07)

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

0.3.1 (2020-03-16)

Bug Fixes

  • theme: make typescript happy (a9aa377)
  • theme: track default theme values dynamically (a0c306c)

0.3.0 (2020-03-11)

Features

  • add "darkest" theme styles (fe38025)

0.2.0 (2020-01-30)

Bug Fixes

  • theme: include "large" scale (67577e7)

Features

  • rework overlays to use popper (e17d1bb)

0.1.1 (2020-01-06)

Bug Fixes

  • factor theme to use a single DOM node (7641228), closes #154
  • get theme element working in storybook (4c5e478)

0.2.3 (2019-12-02)

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

0.2.2 (2019-11-27)

Bug Fixes

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

0.2.1 (2019-11-19)

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

0.2.0 (2019-11-19)

Features

  • use @adobe/spectrum-css@2.15.1 (3918888)

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