Building a Custom Controller

Designing a MediaQueryController

A media query controller should let a component reactively know whether a given CSS media query (like (max-width: 600px)) currently matches, updating automatically as the viewport changes — using the native window.matchMedia() API and its own change event, wrapped in the ReactiveController interface.

Designing a good controller starts the same way as designing a component's properties: decide what public state/methods it exposes, what configuration its constructor needs, and exactly which lifecycle hooks are required to set up and tear down correctly.

export class MediaQueryController {
  host;
  matches;
  #mediaQueryList;
  #onChange = (event) => {
    this.matches = event.matches;
    this.host.requestUpdate();
  };

  constructor(host, query) {
    this.host = host;
    this.#mediaQueryList = window.matchMedia(query);
    this.matches = this.#mediaQueryList.matches;
    host.addController(this);
  }

  hostConnected() {
    this.#mediaQueryList.addEventListener('change', this.#onChange);
  }

  hostDisconnected() {
    this.#mediaQueryList.removeEventListener('change', this.#onChange);
  }
}

The initial matches value is captured synchronously in the constructor, so the very first render already reflects the correct state before any change event has fired.

Using the Finished Controller

class ResponsiveNav extends LitElement {
  #isMobile = new MediaQueryController(this, '(max-width: 600px)');

  render() {
    return this.#isMobile.matches
      ? html`<mobile-menu></mobile-menu>`
      : html`<desktop-menu></desktop-menu>`;
  }
}

• The controller is instantiated once, typically as a private field, right where the component needs it.
• render() reads this.#isMobile.matches directly — no extra property/state wiring needed on the host component itself.
• The controller is fully reusable across any component that needs to react to any media query, not just this one component.
• Consider accepting the media query string as a constructor parameter (as shown) rather than hardcoding it, for maximum reusability.

Custom Controller Design Checklist

Questions to answer while designing any new controller.

Testing a Controller Independently of Any Component

Because a controller is a plain class, not tied to any specific component, you can unit test its logic by passing a minimal fake host object implementing just addController and requestUpdate, without needing to render a real Lit component at all.

test('MediaQueryController updates matches on change', () => {
  const fakeHost = { addController: () => {}, requestUpdate: vi.fn() };
  const controller = new MediaQueryController(fakeHost, '(max-width: 600px)');
  controller.hostConnected();
  // simulate a matchMedia change event, then:
  expect(fakeHost.requestUpdate).toHaveBeenCalled();
});

This kind of isolated, framework-free testability is one of the practical advantages of the controller pattern.

Publishing a Controller as Its Own Package

Because controllers have no dependency on any specific component's internals, a well-designed one can be extracted into its own small, independently versioned package and reused across multiple projects or teams — exactly the model official packages like @lit-labs/task and community media-query controllers already follow.

Common Mistakes

• Hardcoding configuration (like the media query string) directly inside the controller instead of accepting it as a constructor parameter.
• Forgetting to capture the initial state synchronously in the constructor, causing the first render to show a default/incorrect value briefly.
• Not testing a controller in isolation with a fake host, missing an easy opportunity for fast, framework-free unit tests.
• Building a controller so tightly coupled to one specific component's internals that it can't actually be reused anywhere else.

Key Takeaways

• Designing a controller follows the same discipline as designing a component's public property API: decide what's exposed and configurable upfront.
• hostConnected()/hostDisconnected() should always be a matched setup/teardown pair, exactly like a component's own lifecycle hooks.
• Controllers can be unit tested in isolation using a minimal fake host object.
• A well-designed controller can be extracted into its own reusable, independently published package.