Skip to content

API in Performance

Speculation Rules API

Published Updated

The Speculation Rules API lets you tell the browser which URLs to prefetch or fully prerender before navigation, so the next click is answered from memory. Declare the URLs in a JSON block inside <script type="speculationrules">, or point to a JSON file from a Speculation-Rules response header. It replaces <link rel="prefetch"> for documents and the deprecated <link rel="prerender">, which Chrome 63 turned into a NoState Prefetch, and it is Chromium-only in production.

<script type="speculationrules">
{
"prerender": [{ "where": { "href_matches": "/articles/*" }, "eagerness": "moderate" }],
"prefetch": [{ "urls": ["/next.html"] }]
}
</script>
Speculation-Rules: "/rules.json"

The browser parses the block without executing it. Engines that do not support the type ignore it. Chrome 105 (Android 103) started with same-origin prerendering only and Chrome 109 is the first full release, Chrome 121 added the Speculation-Rules header and made the source member optional; Safari 26.2 implements prefetch rules behind the “SpeculationRules prefetch” preference, and Firefox has a partial implementation (URL-list prefetch) in preview builds only (BCD html.elements.script.type.speculationrules).

Member Type Meaning
prefetch, prerender array of rules The action. Prefetch downloads the response; prerender loads and renders the page in a hidden tab, scripts included.
urls array of strings A list rule: explicit URLs. Inline rules resolve them against the document; rules loaded from a file resolve them against the file’s URL unless "relative_to": "document" is set.
where object A document rule: a predicate over links in the page, with href_matches (URL pattern), selector_matches (CSS selector), and and, or, not combinators.
eagerness "immediate", "eager", "moderate", "conservative" When to act. immediate on parse; moderate on desktop after 200 ms of hover or an earlier pointerdown, and on mobile a viewport heuristic since August 2025; conservative on pointerdown; eager behaved as immediate until Chrome 143, where it became a 10 ms hover on desktop and, since January 2026, a viewport heuristic on mobile. List rules default to immediate, document rules to conservative.
requires array ["anonymous-client-ip-when-cross-origin"] matches only if the browser can hide the client IP from a cross-origin prefetch target; Chrome does it with Google’s prefetch proxy.
referrer_policy, tag, expects_no_vary_search, target_hint string Referrer for the speculative request, a label surfaced in DevTools and the Sec-Speculation-Tags header, a No-Vary-Search hint, and the intended target (_self or _blank) for prerenders.

Chrome limits concurrent speculations: 10 prerenders and 50 prefetches for immediate rules, and 2 of each for eager, moderate, and conservative rules, replaced first-in-first-out when a newer candidate appears (Prerender pages in Chrome, developer.chrome.com). Prefetch requests carry Sec-Purpose: prefetch; prerendered documents see document.prerendering === true and receive a prerenderingchange event on activation.

A rule set whose top-level JSON value is not an object fails to parse with a TypeError, and the browser ignores that rule set. DevTools shows the parse status.

Chromium is the only engine with prefetch and prerender rules in a stable release: Chrome and Edge support prerender rules from 105, prefetch rules from 110, with the header form from 121. Safari 26.2 parses prefetch rules only when the “SpeculationRules prefetch” preference is enabled and ignores prerender; Firefox stable ignores the script type, and only preview builds handle URL-list prefetch (BCD html.elements.script.type.speculationrules). An unsupported engine loses nothing but the head start, so rules are safe to ship unconditionally.

Prerendered pages run scripts before navigation, so page-view analytics must wait for activation.

A document rule with moderate eagerness prerenders whichever article the pointer rests on for 200 ms, so the page does not render every link up front. Chrome may still skip a prerender for memory or settings reasons.

<script type="speculationrules">
{
"prerender": [{
"where": { "and": [
{ "href_matches": "/articles/*" },
{ "not": { "selector_matches": ".no-prerender" } }
]},
"eagerness": "moderate"
}]
}
</script>

Links that must not be prerendered, such as sign-out or one-click actions, get the no-prerender class; a prerendered page runs its scripts, so side effects at load time happen before the user has decided to visit.

Code that counts page views must wait for the prerendered page to become visible, or every hovered link counts as a visit.

function onVisible(callback) {
if (document.prerendering) {
document.addEventListener('prerenderingchange', callback, { once: true });
} else {
callback(); // not prerendered (or unsupported engine): run now
}
}
onVisible(() => sendPageView(location.href));

document.prerendering is undefined in engines without the API, which the else branch treats as a normal load. A normal load can still sit in a background tab; wait for visibilitychange when that matters.

Detecting the API and falling back to prefetch

Section titled “Detecting the API and falling back to prefetch”

HTMLScriptElement.supports('speculationrules') is the capability test. The fallback inserts a <link rel="prefetch">, which warms the HTTP cache for the next document in Firefox and Chromium without prerendering.

function speculate(url) {
if (typeof HTMLScriptElement.supports !== 'undefined' && HTMLScriptElement.supports('speculationrules')) {
const script = document.createElement('script');
script.type = 'speculationrules';
script.textContent = JSON.stringify({ prefetch: [{ urls: [url] }] });
document.head.append(script);
return;
}
const link = document.createElement('link'); // fallback: plain prefetch, no prerender
link.rel = 'prefetch';
link.href = url;
document.head.append(link);
}

Rules added by script count towards the same limits as static ones; removing the script element cancels its pending speculations and frees capacity.

Specifications

SpecificationStatus
None.