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
updatefoundand forced an update withskipWaiting()
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.