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.
Syntax
Section titled “Syntax”<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).
Parameters
Section titled “Parameters”| 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.
Exceptions
Section titled “Exceptions”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.
Support by engine
Section titled “Support by engine”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.
Examples
Section titled “Examples”Prerendered pages run scripts before navigation, so page-view analytics must wait for activation.
Prerendering article links on hover
Section titled “Prerendering article links on hover”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.
Deferring analytics until activation
Section titled “Deferring analytics until activation”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.
See also
Section titled “See also”- Speculation Rules (wicg.github.io)
- Prerender pages in Chrome for instant page navigations (developer.chrome.com)
- Debug speculation rules (developer.chrome.com)
- Back/forward cache (bfcache)
- Resource hints (preload and preconnect)
- View Transitions API
Specifications
| Specification | Status |
|---|---|
| None. | |