Page Lifecycle API

Philip Walton

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.

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.

* 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, and pageshow are fired on window; visibilitychange, freeze, and resume are fired on document, and focus and blur 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.

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 or pagehide event listener you can send data to your service worker via postMessage(), 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.