Browser Support
Modern browsers today will sometimes suspend pages or discard them entirely when system resources are constrained. In the future, browsers want to do this proactively, so they consume less power and memory. The Page Lifecycle API provides lifecycle hooks so your pages can safely handle these browser interventions without affecting the user experience. Take a look at the API to see whether you should be implementing these features in your application.
Background
Application lifecycle is a key way that modern operating systems manage resources. On Android, iOS, and recent Windows versions, apps can be started and stopped at any time by the OS. This allows these platforms to streamline and reallocate resources where they best benefit the user.
On the web, there has historically been no such lifecycle, and apps can be kept alive indefinitely. With large numbers of web pages running, critical system resources such as memory, CPU, battery, and network can be oversubscribed, leading to a bad end-user experience.
While the web platform has long had events that related to lifecycle states
— like load
,
unload
, and
visibilitychange
— these events only allow developers
to respond to user-initiated lifecycle state changes. For the web to work
reliably on low-powered devices (and be more resource conscious in general on
all platforms) browsers need a way to proactively reclaim and re-allocate system
resources.
In fact, browsers today already do take active measures to conserve resources for pages in background tabs, and many browsers (especially Chrome) would like to do a lot more of this — to lessen their overall resource footprint.
The problem is developers have no way to prepare for these types of system-initiated interventions or even know that they're happening. This means browsers need to be conservative or risk breaking web pages.
The Page Lifecycle API attempts to solve this problem by:
- Introducing and standardizing the concept of lifecycle states on the web.
- Defining new, system-initiated states that allow browsers to limit the resources that can be consumed by hidden or inactive tabs.
- Creating new APIs and events that allow web developers to respond to transitions to and from these new system-initiated states.
This solution provides the predictability web developers need to build applications resilient to system interventions, and it allows browsers to more aggressively optimize system resources, ultimately benefiting all web users.
The rest of this post will introduce the new Page Lifecycle features and explore how they relate to all the existing web platform states and events. It will also give recommendations and best-practices for the types of work developers should (and should not) be doing in each state.
Overview of Page Lifecycle states and events
All Page Lifecycle states are discrete and mutually exclusive, meaning a page can only be in one state at a time. And most changes to a page's lifecycle state are generally observable via DOM events (see developer recommendations for each state for the exceptions).
Perhaps the easiest way to explain the Page Lifecycle states — as well as the events that signal transitions between them — is with a diagram:
States
The following table explains each state in detail. It also lists the possible states that can come before and after as well as the events developers can use to observe changes.
State | Description |
---|---|
Active |
A page is in the active state if it is visible and has input focus.
Possible previous states: |
Passive |
A page is in the passive state if it is visible and does not have input focus.
Possible previous states:
Possible next states: |
Hidden |
A page is in the hidden state if it is not visible (and has not been frozen, discarded, or terminated).
Possible previous states:
Possible next states: |
Frozen |
In the frozen state the browser suspends execution of
freezable
tasks in the page's
task queues until the page is unfrozen. This means things like
JavaScript timers and fetch callbacks don't run. Already-running
tasks can finish (most importantly the
Browsers freeze pages as a way to preserve CPU/battery/data usage; they also do it as a way to enable faster back/forward navigations — avoiding the need for a full page reload.
Possible previous states:
Possible next states: |
Terminated |
A page is in the terminated state once it has started being unloaded and cleared from memory by the browser. No new tasks can start in this state, and in-progress tasks may be killed if they run too long.
Possible previous states:
Possible next states: |
Discarded |
A page is in the discarded state when it is unloaded by the browser in order to conserve resources. No tasks, event callbacks, or JavaScript of any kind can run in this state, as discards typically occur under resource constraints, where starting new processes is impossible. In the discarded state the tab itself (including the tab title and favicon) is usually visible to the user even though the page is gone.
Possible previous states:
Possible next states: |
Events
Browsers dispatch a lot of events, but only a small portion of them signal a possible change in Page Lifecycle state. The following table outlines all events that pertain to lifecycle and lists what states they may transition to and from.
Name | Details |
---|---|
focus
|
A DOM element has received focus.
Note: a
Possible previous states:
Possible current states: |
blur
|
A DOM element has lost focus.
Note: a
Possible previous states:
Possible current states: |
visibilitychange
|
The document's
|
freeze
*
|
The page has just been frozen. Any freezable task in the page's task queues won't be started.
Possible previous states:
Possible current states: |
resume
*
|
The browser has resumed a frozen page.
Possible previous states:
Possible current states: |
pageshow
|
A session history entry is being traversed to. This could be either a brand new page load or a page taken from the
back/forward cache. If the page
was taken from the back/forward cache, the event's
Possible previous states: |
pagehide
|
A session history entry is being traversed from. If the user is navigating to another page and the browser is able to add
the current page to the back/forward
cache to be reused later, the event's
Possible previous states:
Possible current states: |
beforeunload
|
The window, the document and its resources are about to be unloaded. The document is still visible and the event is still cancelable at this point.
Important: the
Possible previous states:
Possible current states: |
unload
|
The page is being unloaded.
Warning:
using the
Possible previous states:
Possible current states: |
* Indicates a new event defined by the Page Lifecycle API
New features added in Chrome 68
The previous chart shows two states that are system-initiated rather than user-initiated: frozen and discarded. As mentioned previously, browsers today already occasionally freeze and discard hidden tabs (at their discretion), but developers have no way of knowing when this is happening.
In Chrome 68, developers can now observe when a hidden tab is frozen and
unfrozen by listening for the freeze
and resume
events on document
.
document.addEventListener('freeze', (event) => {
// The page is now frozen.
});
document.addEventListener('resume', (event) => {
// The page has been unfrozen.
});
From Chrome 68 the document
object now includes a
wasDiscarded
property on desktop Chrome (Android support is being tracked in this issue). To determine whether a page was discarded while in a hidden
tab, you can inspect the value of this property at page load time (note:
discarded pages must be reloaded to use again).
if (document.wasDiscarded) {
// Page was previously discarded by the browser while in a hidden tab.
}
For advice on what things are important to do in the freeze
and resume
events, as well as how to handle and prepare for pages being discarded, see
developer recommendations for each state.
The next several sections offer an overview of how these new features fit into the existing web platform states and events.
How to observe Page Lifecycle states in code
In the active, passive, and hidden states, it's possible to run JavaScript code that determines the current Page Lifecycle state from existing web platform APIs.
const getState = () => {
if (document.visibilityState === 'hidden') {
return 'hidden';
}
if (document.hasFocus()) {
return 'active';
}
return 'passive';
};
The frozen and terminated states, on the
other hand, can only be detected in their respective event listener
(freeze
and pagehide
) as the state is
changing.
How to observe state changes
Building on the getState()
function defined previously, you can observe all Page
Lifecycle state changes with the following code.
// Stores the initial state using the `getState()` function (defined above).
let state = getState();
// Accepts a next state and, if there's been a state change, logs the
// change to the console. It also updates the `state` value defined above.
const logStateChange = (nextState) => {
const prevState = state;
if (nextState !== prevState) {
console.log(`State change: ${prevState} >>> ${nextState}`);
state = nextState;
}
};
// Options used for all event listeners.
const opts = {capture: true};
// These lifecycle events can all use the same listener to observe state
// changes (they call the `getState()` function to determine the next state).
['pageshow', 'focus', 'blur', 'visibilitychange', 'resume'].forEach((type) => {
window.addEventListener(type, () => logStateChange(getState()), opts);
});
// The next two listeners, on the other hand, can determine the next
// state from the event itself.
window.addEventListener('freeze', () => {
// In the freeze event, the next state is always frozen.
logStateChange('frozen');
}, opts);
window.addEventListener('pagehide', (event) => {
// If the event's persisted property is `true` the page is about
// to enter the back/forward cache, which is also in the frozen state.
// If the event's persisted property is not `true` the page is
// about to be unloaded.
logStateChange(event.persisted ? 'frozen' : 'terminated');
}, opts);
This code does three things:
- Sets the initial state using the
getState()
function. - Defines a function that accepts a next state and, if there's a change, logs the state changes to the console.
- Adds
capturing
event listeners for all necessary lifecycle events, which in turn call
logStateChange()
, passing in the next state.
One thing to note about the code is that all the event listeners are added
to window
and they all pass
{capture: true}
.
There are a few reasons for this:
- Not all Page Lifecycle events have the same target.
pagehide
, andpageshow
are fired onwindow
;visibilitychange
,freeze
, andresume
are fired ondocument
, andfocus
andblur
are fired on their respective DOM elements. - Most of these events don't bubble, which means it's impossible to add non-capturing event listeners to a common ancestor element and observe all of them.
- The capture phase executes before the target or bubble phases, so adding listeners there helps ensure they run before other code can cancel them.
Developer recommendations for each state
As developers, it's important to both understand Page Lifecycle states and know how to observe them in code because the type of work you should (and should not) be doing depends largely on what state your page is in.
For example, it clearly doesn't make sense to display a transient notification to the user if the page is in the hidden state. While this example is pretty obvious, there are other recommendations that aren't so obvious that are worth enumerating.
State | Developer recommendations |
---|---|
Active |
The active state is the most critical time for the user and thus the most important time for your page to be responsive to user input. Any non-UI work that may block the main thread should be deprioritized to idle periods or offloaded to a web worker. |
Passive |
In the passive state the user is not interacting with the page, but they can still see it. This means UI updates and animations should still be smooth, but the timing of when these updates occur is less critical. When the page changes from active to passive, it's a good time to persist unsaved application state. |
When the page changes from passive to hidden, it's possible the user won't interact with it again until it's reloaded. The transition to hidden is also often the last state change
that's reliably observable by developers (this is especially true on
mobile, as users can close tabs or the browser app itself, and the
This means you should treat the hidden state as the likely end to the user's session. In other words, persist any unsaved application state and send any unsent analytics data. You should also stop making UI updates (since they won't be seen by the user), and you should stop any tasks that a user wouldn't want running in the background. |
|
Frozen |
In the frozen state, freezable tasks in the task queues are suspended until the page is unfrozen — which may never happen (e.g. if the page is discarded). This means when the page changes from hidden to frozen it's essential that you stop any timers or tear down any connections that, if frozen, could affect other open tabs in the same origin, or affect the browser's ability to put the page in the back/forward cache. In particular, it's important that you:
You should also persist any dynamic view state (e.g. scroll position
in an infinite list view) to
If the page transitions from frozen back to hidden, you can reopen any closed connections or restart any polling you stopped when the page was initially frozen. |
Terminated |
You generally don't need to take any action when a page transitions to the terminated state. Since pages being unloaded as a result of user action always go through the hidden state before entering the terminated state, the hidden state is where session-ending logic (e.g. persisting application state and reporting to analytics) should be performed. Also (as mentioned in the recommendations for
the hidden state), it's very important for developers to realize
that the transition to the terminated state cannot be reliably
detected in many cases (especially on mobile), so developers who depend
on termination events (e.g. |
Discarded |
The discarded state is not observable by developers at the time a page is being discarded. This is because pages are typically discarded under resource constraints, and unfreezing a page just to allow script to run in response to a discard event is simply not possible in most cases. As a result, you should prepare for the possibility of a discard in
the change from hidden to frozen, and then you can
react to the restoration of a discarded page at page load time by
checking |
Once again, since reliability and ordering of lifecycle events is not consistently implemented in all browsers, the easiest way to follow the advice in the table is to use PageLifecycle.js.
Legacy lifecycle APIs to avoid
The following events should be avoided where at all possible.
The unload event
Many developers treat the unload
event as a guaranteed callback and use it as
an end-of-session signal to save state and send analytics data, but doing this
is extremely unreliable, especially on mobile! The unload
event does not
fire in many typical unload situations, including closing a tab from the tab
switcher on mobile or closing the browser app from the app switcher.
For this reason, it's always better to rely on the
visibilitychange
event to determine when a session
ends, and consider the hidden state the
last reliable time to save app and user data.
Furthermore, the mere presence of a registered unload
event handler (via
either onunload
or addEventListener()
) can prevent browsers from being able
to put pages in the back/forward cache for faster
back and forward loads.
In all modern browsers, it's recommended to always use the
pagehide
event to detect possible page unloads (a.k.a the
terminated state) rather than the unload
event. If you
need to support Internet Explorer versions 10 and lower, you should feature
detect the pagehide
event and only use unload
if the browser doesn't support
pagehide
:
const terminationEvent = 'onpagehide' in self ? 'pagehide' : 'unload';
window.addEventListener(terminationEvent, (event) => {
// Note: if the browser is able to cache the page, `event.persisted`
// is `true`, and the state is frozen rather than terminated.
});
The beforeunload event
The beforeunload
event has a similar problem to the unload
event, in that,
historically, the presence of a beforeunload
event could prevent pages from
being eligible for back/forward cache. Modern browsers
don't have this restriction. Though some browsers, as a precaution, won't fire
the beforeunload
event when attempting to put a page into the back/forward
cache, which means the event is not reliable as an end-of-session signal.
Additionally, some browsers (including Chrome)
require a user-interaction on the page before allowing the beforeunload
event
to fire, further affecting its reliability.
One difference between beforeunload
and unload
is that there are
legitimate uses of beforeunload
. For example, when you want to warn the user
that they have unsaved changes they'll lose if they continue unloading the page.
Since there are valid reasons to use beforeunload
, it's recommended that you
only add beforeunload
listeners when a user has unsaved changes and then
remove them immediately after they are saved.
In other words, don't do this (since it adds a beforeunload
listener
unconditionally):
addEventListener('beforeunload', (event) => {
// A function that returns `true` if the page has unsaved changes.
if (pageHasUnsavedChanges()) {
event.preventDefault();
// Legacy support for older browsers.
return (event.returnValue = true);
}
});
Instead do this (since it only adds the beforeunload
listener when it's
needed, and removes it when it's not):
const beforeUnloadListener = (event) => {
event.preventDefault();
// Legacy support for older browsers.
return (event.returnValue = true);
};
// A function that invokes a callback when the page has unsaved changes.
onPageHasUnsavedChanges(() => {
addEventListener('beforeunload', beforeUnloadListener);
});
// A function that invokes a callback when the page's unsaved changes are resolved.
onAllChangesSaved(() => {
removeEventListener('beforeunload', beforeUnloadListener);
});
FAQs
Why isn't there a "loading" state?
The Page Lifecycle API defines states to be discrete and mutually exclusive. Since a page can be loaded in either the active, passive, or hidden state, and since it can change states—or even be terminated—before it finishes loading, a separate loading state does not make sense within this paradigm.
My page does important work when it's hidden, how can I stop it from being frozen or discarded?
There are lots of legitimate reasons web pages shouldn't be frozen while running in the hidden state. The most obvious example is an app that plays music.
There are also situations where it would be risky for Chrome to discard a page,
like if it contains a form with unsubmitted user input, or if it has a
beforeunload
handler that warns when the page is unloading.
For the moment, Chrome is going to be conservative when discarding pages and only do so when it's confident it won't affect users. For example, pages that have been observed to do any of the following while in the hidden state won't be discarded unless under extreme resource constraints:
- Playing audio
- Using WebRTC
- Updating the table title or favicon
- Showing alerts
- Sending push notifications
For the current list features used to determine whether a tab can be safely frozen or discarded, see: Heuristics for Freezing & Discarding in Chrome.
What is the back/forward cache?
The back/forward cache is a term used to describe a navigation optimization some browsers implement that makes using the back and forward buttons faster.
When a user navigates away from a page, these browsers freeze a version of that
page so that it can be quickly resumed in case the user navigates back using
the back or forward buttons. Remember that adding an unload
event handler prevents this optimization from being possible.
For all intents and purposes, this freezing is functionally the same as the freezing browsers perform to conserve CPU/battery; for that reason it's considered part of the frozen lifecycle state.
If I can't run asynchronous APIs in the frozen or terminated states, how can I save data to IndexedDB?
In frozen and terminated states, freezable tasks in a page's task queues are suspended, which means asynchronous and callback-based APIs such as IndexedDB cannot be reliably used.
In the future, we will add a commit()
method to IDBTransaction
objects, which will
give developers a way to perform what are effectively write-only transactions
that don't require callbacks. In other words, if the developer is just writing
data to IndexedDB and not performing a complex transaction consisting of reads
and writes, the commit()
method will be able to finish before task queues are
suspended (assuming the IndexedDB database is already open).
For code that needs to work today, however, developers have two options:
- Use Session Storage: Session Storage is synchronous and is persisted across page discards.
- Use IndexedDB from your service worker: a service worker can store data in
IndexedDB after the page has been terminated or discarded. In the
freeze
orpagehide
event listener you can send data to your service worker viapostMessage()
, and the service worker can handle saving the data.
Testing your app in the frozen and discarded states
To test how your app behaves in the frozen and discarded states, you can visit
chrome://discards
to actually freeze or discard any of your
open tabs.
This allows you to ensure your page correctly handles the freeze
and resume
events as well as the document.wasDiscarded
flag when pages are reloaded after
a discard.
Summary
Developers who want to respect the system resources of their user's devices should build their apps with Page Lifecycle states in mind. It's critical that web pages are not consuming excessive system resources in situations that the user wouldn't expect
The more developers start implementing the new Page Lifecycle APIs, the safer it will be for browsers to freeze and discard pages that aren't being used. This means browsers will consume less memory, CPU, battery, and network resources, which is a win for users.