Reactive controllers are a powerful tool for code reuse and composition within Lit, a core dependency of Spectrum Web Components. They enable you to extract common behaviors into reusable packages that can be shared across multiple components, reducing code complexity and size while delivering a consistent user experience.

yarn add @spectrum-web-components/reactive-controllers

Reactive controllers are instantiated in your component and automatically hook into the component's lifecycle:

import { LitElement, html } from 'lit';
import { MatchMediaController } from '@spectrum-web-components/reactive-controllers/src/MatchMedia.js';

class MyComponent extends LitElement {
    // Create controller instance
    darkMode = new MatchMediaController(this, '(prefers-color-scheme: dark)');

    render() {
        // Use controller state in render
        return html`
            <div class=${this.darkMode.matches ? 'dark' : 'light'}>Content</div>
        `;
    }
}

Reactive controllers implement the ReactiveController interface with the following optional lifecycle methods:

• hostConnected(): Called when the host element is connected to the DOM
• hostDisconnected(): Called when the host element is disconnected from the DOM
• hostUpdate(): Called before the host's update() method
• hostUpdated(): Called after the host's update() method

Controllers can also call host.requestUpdate() to trigger an update cycle on the host element.

You can create custom reactive controllers by implementing the ReactiveController interface:

import { ReactiveController, ReactiveElement } from 'lit';

export class MyController implements ReactiveController {
    private host: ReactiveElement;

    constructor(host: ReactiveElement) {
        this.host = host;
        // Register this controller with the host
        this.host.addController(this);
    }

    hostConnected() {
        // Called when host is connected to DOM
    }

    hostDisconnected() {
        // Called when host is disconnected from DOM
    }
}

Manages and validates color values in various color spaces (RGB, HSL, HSV, Hex). Provides conversion between formats and state management for color-related interactions.

Use cases:

• Color pickers and selectors
• Color input validation
• Color format conversion
• Theme customization UIs

Key features:

• Multiple color format support (hex, RGB, HSL, HSV)
• Color validation
• Format preservation
• Undo/redo support

Learn more →

Manages the availability of custom element dependencies, enabling lazy loading patterns and progressive enhancement strategies.

Use cases:

• Code splitting and lazy loading
• Progressive enhancement
• Route-based component loading
• Conditional feature loading

Key features:

• Tracks custom element registration
• Reactive loading state
• Multiple dependency management
• Works with dynamic imports

Learn more →

Maintains an active reference to another element in the DOM tree, automatically tracking changes and updating when the DOM mutates.

Use cases:

• Accessible label associations
• Focus trap management
• Form validation connections
• Dynamic element relationships

Key features:

• Automatic DOM observation
• ID selector optimization
• Shadow DOM support
• Reactive updates

Learn more →

Base controller for managing keyboard focus within groups of elements. Extended by RovingTabindexController with tabindex management capabilities.

Use cases:

• Custom composite widgets
• Keyboard navigation patterns
• Focus management

Key features:

• Arrow key navigation
• Configurable direction modes
• Focus entry points
• Element enter actions

Note: This controller is typically not used directly. Use RovingTabindexController instead for most use cases.

Resolves and tracks the language/locale context of the host element, responding to changes in the lang attribute up the DOM tree.

Use cases:

• Internationalization (i18n)
• Localized content
• RTL/LTR text direction
• Locale-specific formatting

Key features:

• Automatic language detection
• Locale change tracking
• Supports Shadow DOM
• Bubbles up DOM tree

Learn more →

Binds CSS media queries to reactive elements, automatically updating when queries match or unmatch.

Use cases:

• Responsive design
• Dark mode detection
• Mobile/desktop layouts
• Print styles
• Accessibility preferences (prefers-reduced-motion, etc.)

Key features:

• Multiple media query support
• Reactive updates
• Predefined queries (DARK_MODE, IS_MOBILE)
• Event-driven

Learn more →

Manages pending/loading states for interactive elements, providing visual feedback and accessible state communication.

Use cases:

• Async button actions
• Form submission states
• Loading indicators
• Progress feedback

Key features:

• Automatic ARIA label management
• Progress circle rendering
• Label caching and restoration
• Disabled state awareness

Note: Currently used primarily by Button component. May be deprecated in future versions.

Learn more →

Implements the W3C ARIA roving tabindex pattern for keyboard navigation in composite widgets, managing tabindex attributes and arrow key navigation.

Use cases:

• Toolbars
• Tab lists
• Menus
• Radio groups
• Listboxes
• Grids

Key features:

• Arrow key navigation (with Home/End support)
• Automatic tabindex management
• Flexible direction modes (horizontal, vertical, both, grid)
• Skips disabled elements
• WCAG compliant

Learn more →

Resolves and tracks system-level context like color scheme and scale preferences from Spectrum theme providers.

Use cases:

• Theme integration
• Design system variant detection (Spectrum Classic, Express, Spectrum 2)
• System-specific asset loading
• Adaptive UI rendering

Key features:

• Automatic theme context resolution
• Reactive system variant updates
• Event-based communication with <sp-theme>
• Automatic cleanup on disconnect

Note: Private Beta API - subject to changes.

Learn more →

Changelog

• #5730 7d23140 Thanks @caseyisonit! - - Fixed: Accessibility and caching in PendingStateController.

  • Fixed: Updated progress circle to use role="presentation" for better accessibility compliance
  • Fixed: Improved aria-label caching logic to better handle dynamic label changes
  • Added: Documentation noting the controller is primarily used by <sp-button> component
  • Fixed: Enhanced caching mechanism to preserve user-set aria-labels during pending states

  These changes improve accessibility compliance and aria-label management for components using the pending state controller.

• Updated dependencies [7d23140]:

  • @spectrum-web-components/progress-circle@1.9.0

• Updated dependencies []:
  • @spectrum-web-components/progress-circle@1.8.0

• Updated dependencies []:
  • @spectrum-web-components/progress-circle@1.7.0

• Updated dependencies []:
  • @spectrum-web-components/progress-circle@1.6.0

• Updated dependencies []:
  • @spectrum-web-components/progress-circle@1.5.0

• Updated dependencies []:
  • @spectrum-web-components/progress-circle@1.4.0

• #5031 ea38ef0 Thanks @nikkimk! - Used WAI ARIA Authoring Practices Guide (APG) to make accessibility improvements for <sp-action-menu>, <sp-menu>, and <sp-picker>, including:

  • Numpad keys now work with <sp-picker> and <sp-action-menu> -<sp-action-menu>'s <sp-menu-item> elements can now be read by a screen reader (#4556)
  • <sp-menu-item> href can now be clicked by a screen reader (#4997)
  • Opening a <sp-action-menu>, <sp-menu>, and <sp-picker> with a keyboard now sets focus on an item within the menu. (#4557)

  See the following APG examples for more information:

  • Navigation Menu Example
  • Editor Menubar Example

• Updated dependencies []:
  • @spectrum-web-components/progress-circle@1.3.0

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

• action menu: keyboard accessibility omnibus (#5031) (ea38ef0), closes #4623

• reactive-controllers: Migrate to Colorjs from Tinycolor (#4713) (9d740f0)

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

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

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

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

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

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

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

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

• reactive-controller: new pending state controller (#4605) (68baf94)

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

• reactive-controllers: update focusable element's tab-index to 0 on accepting focus (#4630) (d359e84)

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

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

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

• action-bar: support for action-menus (#3780) (4aff599)

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

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

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

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

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

• reactive-controllers: add DependencyManagerController (c7f7dea)

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

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

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

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

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

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

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

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

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

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

• support numeric IDs when resolving elements (f62bf0d)

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

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

• grid: grid focusgroup fix on mutationObserver (#3684) (5d47db5)

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

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

• overlay: ship Overlay API v2 (67b5d1b)

• added default focus in focus group (cd59f18)
• added Mutation Observer in the tags workflow (3af1861)
• reactive-controllers: functionality debugged (f98013b)
• reactive-controllers: handleItemMutation (d0e32a2)
• removed disabled property check (816732f)
• removed mutation controller from tags and added to focusgroup (aaa1bc0)
• tags: corner cases handled (8ec6b6a)
• tags: delete functionality working (60e6c2e)
• tags: documented the function (f97c7a7)
• tags: handled corner cases (55a95b7)
• tags: performed the suggested changes (6e3ef36)
• tags: removed comment (771dc0e)
• tags: some extra chnages (45f1a9d)
• tags: some minor chnages (36886fc)
• tags: suggested changes done (8aca49e)

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

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

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

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

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

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

• add Grid pattern (341f493)
• add support for Element Resolution (d6a65d0)
• convert the langage resolution workflow to a Reactive Controller (b7781db)
• ensure reactivity of resolved language (5863a15)
• leverage Color Controller to unify color interface across packages (fb71690)
• manage updated node types (0517fc1)
• table: add resize controller to TableBody for a11y reasons (85dd406)

• add reactive controllers package (d434e9d)
• include all Dev Mode files in side effects (f70817c)
• modified .selected to make <sp-action-group> a controllable component (#2006) (4c69b25)
• picker: support responsive delivery of menu (20031d1)

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

• add support for Element Resolution (d6a65d0)

• ensure reactivity of resolved language (5863a15)

• manage updated node types (0517fc1)

• convert the langage resolution workflow to a Reactive Controller (b7781db)
• leverage Color Controller to unify color interface across packages (fb71690)
• table: add resize controller to TableBody for a11y reasons (85dd406)

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

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

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

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

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

• add Grid pattern (341f493)

• picker: support responsive delivery of menu (20031d1)

• add reactive controllers package (d434e9d)
• modified .selected to make <sp-action-group> a controllable component (#2006) (4c69b25)