Find which navigations were blocked from using the bfcache, and why.
 Chris Mills [X](https://twitter.com/chrisdavidmills) [GitHub](https://github.com/chrisdavidmills) [LinkedIn](https://www.linkedin.com/in/chris-mills-4471711)  Barry Pollard [X](https://twitter.com/tunetheweb) [GitHub](https://github.com/tunetheweb) [Mastodon](https://mastodon.social/@tunetheweb) [Bluesky](https://bsky.app/profile/tunetheweb.com) [Homepage](https://www.tunetheweb.com)
The `notRestoredReasons` property, added to the [`PerformanceNavigationTiming`](https://developer.mozilla.org/docs/Web/API/PerformanceNavigationTiming) class, reports information on whether frames present in the document were blocked from using the [bfcache](https://web.dev/articles/bfcache) on navigation, and why. Developers can use this information to identify pages that need updates to make them bfcache-compatible, thereby improving site performance.
## Current status
The `notRestoredReasons` API has shipped from Chrome 123 and is being rolled out gradually.
> [!NOTE]
> **Note:** Differences since the origin trial.
>
>
> From Chrome 109 until 114
> [the API was available as an origin trial](https://developer.chrome.com/origintrials#/view_trial/3101854243351429121).
> This had a number of differences to the shipped API following feedback through the standardisation process:
>
> - A `blocked` boolean (named `preventedBackForwardCache` in previous iterations) indicated whether the bfcache was blocked. This was removed as it can be inferred from the presence of blocking reasons.
> - The `reasons` value, was an array of strings but is now an array of objects.
> - The reason texts were updated (see [note about avoid depending on specific text](https://developer.chrome.com/docs/web-platform/bfcache-notrestoredreasons.md.txt#avoid-depending-on-reason-text)).
> - Empty attributes were represented as empty strings (`""`) but now are `null`.
## Concepts and usage
Modern browsers provide an optimization feature for history navigation called the [back/forward cache](https://web.dev/articles/bfcache) (bfcache). This enables an instant loading experience when users go back to a page they have already visited. Pages can be blocked from entering the bfcache or get evicted while in bfcache for different reasons, some required by a specification and some specific to browser implementations.
Previously, there was no way for developers to find out why their pages were blocked from using the bfcache in the field, though there was a [test in Chrome dev tools](https://web.dev/articles/bfcache#test_to_ensure_your_pages_are_cacheable). To enable monitoring in the field, the [`PerformanceNavigationTiming`](https://developer.mozilla.org/docs/Web/API/PerformanceNavigationTiming) class has been extended to include a `notRestoredReasons` property. This returns an object containing related information on the top frame and all iframes present in the document:
- Reasons why they were blocked from using the bfcache.
- Details such as frame `id` and `name`, to help identify iframes in the HTML.
This allows developers to take action to make those pages bfcache-compatible, thereby improving site performance.
## Examples
A [`PerformanceNavigationTiming`](https://developer.mozilla.org/docs/Web/API/PerformanceNavigationTiming) instance can be obtained from features such as [`Performance.getEntriesByType()`](https://developer.mozilla.org/docs/Web/API/Performance/getEntriesByType) and [`PerformanceObserver`](https://developer.mozilla.org/docs/Web/API/PerformanceObserver).
For example, you could invoke the following function to return all `PerformanceNavigationTiming` objects present in the performance timeline and log their `notRestoredReasons`:
```javascript
function returnNRR() {
const navEntries = performance.getEntriesByType("navigation");
for (let i = 0; i < navEntries.length; i++) {
console.log(`Navigation entry ${i}`);
let navEntry = navEntries[i];
console.log(navEntry.notRestoredReasons);
}
}
```
For history navigations, the `PerformanceNavigationTiming.notRestoredReasons` property returns an object with the following structure, which represents the blocked state of the top-level frame:
```javascript
{
children: [],
id: null,
name: null,
reasons: [
{"reason", "unload-listener"}
],
src: null,
url: "https://www.example.com/page/"
}
```
The properties are as follows:
`children`
: An array of objects representing the blocked state of any same-origin frames embedded in the top-level frame. Each object has the same structure as the parent object --- this way, any number of levels of embedded frames can be represented inside the object recursively. If the frame has no children, the array will be empty.
`id`
: A string representing the `id` attribute value of the frame (for example `