Course contentsShow
← Web Development
Lesson 2383 of 2,98243. Service Workers Deep DiveFree lesson

The controllerchange Event

Responding when a new service worker takes control of the page with controllerchange.

The controllerchange Event

You'll learn: how to detect and respond when a new service worker takes over as the active controller of your page.

What is controllerchange?

The controllerchange event fires on the navigator.serviceWorker object whenever a new service worker becomes the active controller of the current page. This happens after a service worker has been installed, activated, and has called clients.claim() to take immediate control—or when the page first loads under a newly activated service worker.

Think of it like a changing of the guard: when one service worker "hands off" control to another, this event lets your page know that the handoff is complete. It's your cue that the page is now being served by a different version of your service worker.

When Does It Fire?

The event typically fires in these scenarios:

  • A new service worker has just activated and called clients.claim(), taking control of already-open pages
  • The user navigates to a page that's controlled by a service worker for the first time
  • After you've handled updatefound and forced an update with skipWaiting()

Listening for the Event

navigator.serviceWorker.addEventListener('controllerchange', () => {
  console.log('New service worker now in control!');
  
  // Common response: reload to get fresh assets
  window.location.reload();
});

This is often paired with your update flow—once controllerchange fires, you know the new service worker is active and you might want to reload the page to ensure all resources are fresh and in sync with the new service worker's logic.

Practical Use

This event is crucial for providing a seamless update experience. After detecting an update with updatefound, calling skipWaiting(), and having the new worker claim clients, controllerchange confirms everything is ready—making it the perfect moment to refresh the page or notify users that an update has been applied.

Key Takeaway: The controllerchange event fires when a new service worker takes control of your page, signaling that it's safe to reload or update your UI to match the new service worker version.