Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 38 ยท Reactive Properties

Reactive Controllers in Lit

Build reusable, stateful logic for Lit components with reactive controllers: hostConnected, hostUpdate, requestUpdate, a timer, a mouse tracker and a media query controller.

Sooner or later two components need the same behavior: tracking the mouse, watching a media query, polling a server, debouncing input. Copy and paste works until the behavior needs cleanup on removal. Inheritance forces one base class. Lit's answer is the reactive controller: a plain object that hooks into a component's lifecycle and can ask the component to re-render.

A controller is the Lit equivalent of a composable or a hook, written as an ordinary class. You can test it on its own, share it across components, and combine as many as you need in one element.

The controller contract

A reactive controller is any object with some of these optional methods:

Method Called when
hostConnected() the host element is added to the document
hostDisconnected() the host is removed
hostUpdate() before the host's update() (like willUpdate)
hostUpdated() after the host has rendered

To get these calls you register the controller in the host's constructor with host.addController(this). To make the host re-render when your data changes, call host.requestUpdate().

JavaScript
class MyController {
  constructor(host) {
    this.host = host;
    host.addController(this);
  }
  hostConnected() { /* start */ }
  hostDisconnected() { /* stop */ }
}

A clock controller

The classic first controller owns a timer. It starts the interval when the host connects, stops it when the host disconnects, and requests a re-render on every tick.

ClockController

The component itself contains no timer code at all. It only says "I have a clock" (clock = new ClockController(this)) and reads this.clock.value in render. (A class field is fine here because clock is a plain field, not a declared reactive property.)

What a controller does

Hooks in host.addController(this)
Owns logic Timers, listeners, fetches
Asks for render host.requestUpdate()
Cleans up hostDisconnected()

Reusable like a hook, testable like a class.

1 / 2

A mouse-position controller

Controllers shine when they attach global listeners, because the add/remove pair lives in one place.

MouseController

The handler is an arrow-function field so this stays bound and the same reference works for both add and remove.

Controllers that read host properties

A controller can read the host's current properties and react in hostUpdate. This one counts how many times a chosen property changed.

ChangeCounter

hostUpdate runs before render(), so the new count is already visible to the template in the same update. No extra render is needed.

An async controller: fetching data

A controller can also manage a loading/error/data state machine, which keeps every component that fetches from repeating the same code. This stand-in uses a fake fetch so it runs in the sandbox.

FetchController

Lit's own @lit/task package ships a production version of this pattern (Task); the idea is the same, with cancellation and caching added. In a real project you would reach for it.

Design guidelines

  • Constructor takes the host first. new MyController(this, ...options) is the convention.
  • Register in the constructor, not in connectedCallback. Lit calls hostConnected immediately if the host is already connected.
  • Always clean up in hostDisconnected. Anything you start in hostConnected must stop there.
  • Call requestUpdate() only when the visible value changes. Calling it every tick wastes renders.
  • Expose plain properties. The component reads controller.value; keep the surface tiny.
  • Do not store the host's DOM. Query it in hostUpdated, when it exists.

Because a controller is a class with no DOM, you can unit-test it with a tiny fake host: an object with addController and requestUpdate methods. The testing lessons show the pattern.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does a controller get lifecycle callbacks from its host?

    addController registers the object; Lit then calls hostConnected, hostUpdate, hostUpdated and hostDisconnected.
  2. 2. A controller's data changed. How does it make the host show the new data?

    requestUpdate queues a normal update, so the host re-renders and reads the controller's new value.
  3. 3. Where must a controller remove a window event listener it added?

    hostDisconnected runs when the host leaves the document, which is the moment to stop timers and listeners.
  4. 4. What is the main advantage of controllers over a shared base class?

    A class can extend only one parent, but it can hold any number of controllers.

Summary

  • A reactive controller is a plain object attached with host.addController(this).
  • It reacts to hostConnected, hostDisconnected, hostUpdate and hostUpdated, and calls host.requestUpdate() to re-render.
  • Use controllers for timers, global listeners, media queries and data loading, keeping components small.
  • Always clean up in hostDisconnected.

Next: Dispatching Custom Events