@spectrum-web-components/reactive-controllers

Overview

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.

$3

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

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

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

;
}
}
`

$3

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.

$3

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

`typescript
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
}
}
`

$3

#### ColorController

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 →

---

#### DependencyManagerController

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 →

---

#### ElementResolutionController

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 →

---

#### FocusGroupController

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.

---

#### LanguageResolutionController

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 →

---

#### MatchMediaController

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 →

---

#### PendingStateController

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 →

---

#### RovingTabindexController

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 →

---

#### SystemContextResolutionController

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 `
- Automatic cleanup on disconnect

Note: Private Beta API - subject to changes.

Learn more →