Use the chrome.webNavigation module to receive notifications about the status of navigations requests in-flight.

Manifest

All chrome.webNavigation methods and events require you to declare the "webNavigation" permission in the extension manifest. For example:

{
  "name": "My extension",
  ...
  "permissions": [
    "webNavigation"
  ],
  ...
}

Examples

You can find simple examples of using the tabs module in the examples/api/webNavigation directory. For other examples and for help in viewing the source code, see Samples.

Event order

For a navigation that is successfully completed, events are fired in the following order:

onBeforeNavigate -> onCommitted -> onDOMContentLoaded -> onCompleted

Any error that occurs during the process results in an onErrorOccurred event. For a specific navigation, there are no further events fired after onErrorOccurred.

If a navigating frame contains subframes, its onCommitted is fired before any of its children's onBeforeNavigate; while onCompleted is fired after all of its children's onCompleted.

If the reference fragment of a frame is changed, a onReferenceFragmentUpdated event is fired. This event can fire any time after onDOMContentLoaded, even after onCompleted.

Relation to webRequest events

There is no defined ordering between events of the webRequest API and the events of the webNavigation API. It is possible that webRequest events are still received for frames that already started a new navigation, or that a navigation only proceeds after the network resources are already fully loaded.

In general, the webNavigation events are closely related to the navigation state that is displayed in the UI, while the webRequest events correspond to the state of the network stack which is generally opaque to the user.

A note about timestamps

It's important to note that some technical oddities in the OS's handling of distinct Chrome processes can cause the clock to be skewed between the browser itself and extension processes. That means that WebNavigation's events' timeStamp property is only guaranteed to be internally consistent. Comparing one event to another event will give you the correct offset between them, but comparing them to the current time inside the extension (via (new Date()).getTime(), for instance) might give unexpected results.