# @spectrum-web-components/reactive-controllers

> ReactiveControllers for powering common UI patterns

Latest version **1.12.5** (published 2026-10-14) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @spectrum-web-components/reactive-controllers
pnpm add @spectrum-web-components/reactive-controllers
yarn add @spectrum-web-components/reactive-controllers
bun add @spectrum-web-components/reactive-controllers
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.12.5 |
| Published | 2026-10-14 |
| First published | 2022-01-26 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1576 |
| Author | Adobe |
| Maintainers | caseyisonit, taratadobe, rajrock38, jnjosh, nikkimk, rubenc, jianliao79, pvashish, patrickfulton |
| Keywords | design-system, spectrum, adobe, adobe-spectrum, web components, web-components, lit-element, lit-html, component, css |

## Links

- npm: https://www.npmjs.com/package/@spectrum-web-components/reactive-controllers
- Repository: https://github.com/adobe/spectrum-web-components
- Homepage: https://opensource.adobe.com/spectrum-web-components/tools/reactive-controllers
- Issues: https://github.com/adobe/spectrum-web-components/issues
- npm.io page: https://npm.io/package/@spectrum-web-components/reactive-controllers

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 1.12.5 (latest) — 2026-10-14
- 1.12.3-next.20260903033550 (next) — 2026-09-03
- 1.12.3-snapshot-test.20260831180357 (snapshot-test) — 2026-08-31
- 1.12.3-test.20260827122947 (test) — 2026-08-27
- 1.12.0-snapshot.20260422090428 (snapshot) — 2026-04-22
- 1.12.0-snaphot-test.20260223152537 (snaphot-test) — 2026-02-23
- 1.12.0-testing.20260223092154 (testing) — 2026-02-23
- 1.11.0-preview-ae61361d.20251203202755 (preview) — 2025-12-03
- 1.9.1-nightly.20251101120150 (nightly) — 2025-11-01
- 1.6.1-beta.0 (beta) — 2025-05-05
- 0.0.0-20250410163257 (calendar) — 2025-04-10
- 1.0.1-color-testing (color-testing) — 2024-12-09
- 1.0.0-rc.10 (rc) — 2024-10-30
- 1.12.4 — 2026-09-29
- 1.12.3-next.20260901142734 — 2026-09-01
- … 341 more at https://npm.io/package/@spectrum-web-components/reactive-controllers/versions

## README

## Overview

[Reactive controllers](https://lit.dev/docs/composition/controllers/) are a powerful tool for code reuse and composition within [Lit](https://lit.dev), 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.

### Usage

```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`
      <div class=${this.darkMode.matches ? 'dark' : 'light'}>Content</div>
    `;
  }
}
```

### Controller lifecycle

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.

### Creating your own controllers

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

### Available controllers

#### 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 →](../color-controller)

---

#### 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 →](../dependency-manager)

---

#### 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 →](../element-resolution)

---

#### 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](../roving-tab-index) 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 →](../language-resolution)

---

#### 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 →](../match-media)

---

#### 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 →](../pending-state)

---

#### 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 →](../roving-tab-index)

---

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

**Note:** Private Beta API - subject to changes.

[Learn more →](../system-context-resolution)

---
_Source: https://npm.io/package/@spectrum-web-components/reactive-controllers · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._