@spectrum-web-components/theme
Advanced tools
`sp-theme` applies a Spectrum theme by using CSS custom properties to set default sizes & colors for all of the components in its scope. The Spectrum design system provides four color themes (`lightest`, `light`, `dark`, and `darkest`) and two different s
sp-theme applies a Spectrum theme by using CSS custom properties to set default sizes & colors for all of the components in its scope. The Spectrum design system provides four color themes (lightest, light, dark, and darkest) and two different scales (medium and large) to support desktop & mobile UI.
yarn add @spectrum-web-components/theme
import '@spectrum-web-components/theme/sp-theme.js';
import '@spectrum-web-components/theme/src/themes.js';
The above import statements do two things: the first will get you started using the <sp-theme> wrapper element, and the second includes all four (4) color options (lightest, light, dark, and darkest) and both (2) scale options (medium and large) for the Spectrum Classic theme. Having all of these options available together is the easiest way to get a handle on the theming possibilities offered by the package and empowers you to prototype and test various deliveries of your application. However, reserving the download and parse time for all of the variants may not be required for all applications. See the "Advanced usage" section below for instructions on tuning the performance of an application that leverages this package.
Below are more ways to import the different scale and color options individually, in case you didn't want to import all of them as we did above. You'll use these statements in combination with the side effectful registration import statement import '@spectrum-web-components/theme/sp-theme.js'.
The various Classic themes can be imported en masse, as in the example above:
import '@spectrum-web-components/theme/src/themes.js';
The various Spectrum Express themes can also be imported en masse:
import '@spectrum-web-components/theme/src/express/themes.js';
Or you can import the themes and scales individually:
import '@spectrum-web-components/theme/theme-darkest.js';
import '@spectrum-web-components/theme/theme-dark.js';
import '@spectrum-web-components/theme/theme-light.js';
import '@spectrum-web-components/theme/theme-lightest.js';
import '@spectrum-web-components/theme/scale-medium.js';
import '@spectrum-web-components/theme/scale-large.js';
import '@spectrum-web-components/theme/express/theme-darkest.js';
import '@spectrum-web-components/theme/express/theme-dark.js';
import '@spectrum-web-components/theme/express/theme-light.js';
import '@spectrum-web-components/theme/express/theme-lightest.js';
import '@spectrum-web-components/theme/express/scale-medium.js';
import '@spectrum-web-components/theme/express/scale-large.js';
When looking to leverage the Theme base class as a type and/or for extension purposes, do so via:
import { Theme } from '@spectrum-web-components/theme';
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.
An <sp-theme> element expects a value for each of its color and scale attributes to be provided on the element. While not required, you can also use the system attribute to specify whether the theme you're using is Spectrum Classic (the default), Spectrum 2 (upcoming release) or Spectrum Express.
<sp-theme
system="spectrum"
color="light"
scale="medium"
style="background-color: var(--spectrum-gray-100)"
>
<sp-button onclick="spAlert(this, 'Themed <sp-button> clicked!')">
Click me!
</sp-button>
</sp-theme>
Once you've moved beyond the prototype phase of an application, it is likely that you will only use one combination of color and scale in your application, and even if not, you'll likely benefit from lazily loading the variants you don't leverage by default. For single combination applications, or to power a default theme, the following imports can be used to ensure only the code your application requires is loaded:
/**
* Power a site using
*
* <sp-theme
* system="spectrum"
* color="darkest"
* scale="large"
* >
**/
import '@spectrum-web-components/theme/theme-darkest.js';
import '@spectrum-web-components/theme/scale-large.js';
import '@spectrum-web-components/theme/sp-theme.js';
/**
* Power a site using
*
* <sp-theme
* system="express"
* color="light"
* scale="medium"
* >
**/
import '@spectrum-web-components/theme/express/theme-light.js';
import '@spectrum-web-components/theme/express/scale-medium.js';
import '@spectrum-web-components/theme/sp-theme.js';
When subsequent theme variants are needed, you can ensure those are lazily loaded by leveraging dynamic imports via something like:
const themeElement = document.querySelector('sp-theme');
const updateTheme = async (color, scale) => {
Promise.all([
import(`@spectrum-web-components/theme/theme-${color}.js`),
import(`@spectrum-web-components/theme/scale-${scale}.js`),
]).then(() => {
themeElement.color = color;
themeElement.scale = scale;
});
};
updateTheme('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.
<style type="text/css">
#example {
max-width: 500px;
padding: 3em;
background-color: var(--spectrum-gray-100);
color: var(--spectrum-gray-800);
}
#buttons {
margin-top: 2em;
}
</style>
<sp-theme system="express" color="light" scale="medium">
<hzn-app-stuff></hzn-app-stuff>
</sp-theme>
<express-app>
<hzn-app-stuff></hzn-app-stuff>
</express-app>
<style type="text/css">
#example {
max-width: 500px;
padding: 3em;
background-color: var(--spectrum-gray-100);
color: var(--spectrum-gray-800);
}
#buttons {
margin-top: 2em;
}
</style>
<sp-theme system="express" color="dark" scale="large">
<hzn-app-stuff></hzn-app-stuff>
</sp-theme>
<express-app>
<hzn-app-stuff></hzn-app-stuff>
</express-app>
The large scale of <sp-theme> will switch to using Spectrum's larger mobile Platform Scale
<style type="text/css">
#example {
max-width: 500px;
padding: 1em;
background-color: var(--spectrum-gray-100);
color: var(--spectrum-gray-800);
}
#buttons {
margin-top: 2em;
}
</style>
<sp-theme color="darkest" scale="large">
<div id="example">
<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>
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>
The <sp-theme> element provides a language context for its descendents in the DOM. Descendents can resolve this context by dispatching an sp-language-context DOM event and supplying a callback(lang: string) => void method in the detail entry of the Custom Event. These callbacks will be reactively envoked when the lang attribute on the <sp-theme> element is updated. This way, you can control the resolved language in <sp-number-field>, <sp-slider>, and other elements in one centralized place.
The element provides a "system" context to its descendants in the DOM. This context indicates the Spectrum design system variant currently in use (e.g., 'spectrum', 'express', or 'spectrum-two').
Components can consume the system context by using the SystemResolutionController. This controller encapsulates the logic for resolving the system context, allowing it to be integrated into any component in few steps.
SystemResolutionController and the necessary types:import {
SystemResolutionController,
systemResolverUpdatedSymbol,
} from './SystemResolutionController.js';
import type { SystemVariant } from '@spectrum-web-components/theme';
Instantiate the SystemResolutionController:
In your component class, create an instance of SystemResolutionController, passing this as the host element.
export class MyComponent extends LitElement {
private systemResolver = new SystemResolutionController(this);
// Rest of your component code...
}
Respond to system context changes:
Override the update lifecycle method to detect changes in the system context using the systemResolverUpdatedSymbol.
protected update(changes: Map<PropertyKey, unknown>): void {
super.update(changes);
if (changes.has(systemResolverUpdatedSymbol)) {
this.handleSystemChange();
}
}
Implement the handler for system changes:
Create a method that will be called whenever the system context changes. Use this.systemResolver.system to access the current system variant.
private handleSystemChange(): void {
const currentSystem: SystemVariant = this.systemResolver.system;
// Implement logic based on the current system variant.
// For example, update styles, states or re-render parts of the component.
}
Use the system context in other parts of your component logic and/or template:
You can now use this.systemResolver.system anywhere in your component to adjust behavior or rendering based on the system variant.
render() {
return html`
<div>
<!-- Use the system context in your rendering logic -->
Current system variant: ${this.systemResolver.system}
</div>
`;
}
1.7.0 (2025-06-11)
sp-overlay: Fixed : Overlays (like pickers and action menus) were incorrectly closing when scrolling occurred within components. The fix ensures the handleScroll method in OverlayStack only responds to document/body scrolling events and ignores component-level scrolling events, which was the original intention.
sp-card: Fixed: On mobile Chrome (both Android and iOS), scrolling on sp-card components would inadvertently trigger click events. This was caused by the timing-based click detection (200ms threshold) in the pointer event handling, which could misinterpret quick scrolls as clicks. This issue did not affect Safari on mobile devices.
sp-action-button: - Fixed : Action buttons with href attributes now properly detects modifier keys and skips the proxy click, allowing only native browser behavior to proceed.
sp-styles: Remove unnecessary system theme references to reduce complexity for components that don't need the additional mapping layer.
sp-card: - Fixed: sp-card component relies on sp-popover for certain toggle interactive behaviors, but this dependency was missing from its dependency tree.
sp-menu: Fixes: Icons in menu stories weren't properly responding to theme changes when used in functional story components. Switching to class-based LitElement components ensures proper component lifecycle hooks and shadow DOM context for icon initialization and theme integration.
sp-tabs: Added @spectrum-web-components/action-button as a dependency for Tabs as its used in the direction button.
sp-split-view: Added @spectrum-web-components/shared dependency in splitview since it uses ranDomId from the shared package
sp-textfield: Replace deprecated word-break: break-word with overflow-wrap: break-word to align with modern CSS standards and improve cross-browser compatibility. This property was deprecated in Chrome 44 (July 2015) in favor of the standardized overflow-wrap property.
FAQs
`sp-theme` applies a Spectrum theme by using CSS custom properties to set default sizes & colors for all of the components in its scope. The Spectrum design system provides four color themes (`lightest`, `light`, `dark`, and `darkest`) and two different s
The npm package @spectrum-web-components/theme receives a total of 10,938 weekly downloads. As such, @spectrum-web-components/theme popularity was classified as popular.
We found that @spectrum-web-components/theme demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 7 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A RubyGems malware campaign used 60 malicious packages posing as automation tools to steal credentials from social media and marketing tool users.
Security News
The CNA Scorecard ranks CVE issuers by data completeness, revealing major gaps in patch info and software identifiers across thousands of vulnerabilities.
Research
/Security News
Two npm packages masquerading as WhatsApp developer libraries include a kill switch that deletes all files if the phone number isn’t whitelisted.