Speculation Rules API: Definition and Example

The Speculation Rules API lets a web page tell the browser which URLs a visitor will probably open next. The browser then prefetches those pages or prerenders them in a hidden tab, so the navigation feels instant.

How does it work?

Rules are written as JSON inside a <script type="speculationrules"> element, or in a file referenced by the Speculation-Rules HTTP header. MDN says the API supersedes the deprecated <link rel="prerender">.

Prefetch downloads only the response body of the page, without subresources. It is cheap.
Prerender fetches and renders the whole page, including JavaScript, in an invisible tab. MDN compares the cost to rendering an iframe and advises using it sparingly.
Eagerness controls when speculation starts. Chrome documents immediate (as soon as the rules are observed), eager (after a very short hover of 10 ms on desktop), moderate (after a 200 ms hover on desktop) and conservative (on pointer or touch down). Mobile uses viewport heuristics for eager and moderate.
Document rules use patterns such as href_matches instead of fixed URL lists.

Example

HTML

<script type="speculationrules">
{
  "prerender": [{
    "where": { "and": [
      { "href_matches": "/*" },
      { "not": { "href_matches": "/logout" } }
    ]},
    "eagerness": "moderate"
  }]
}
</script>

Common mistakes

Prerendered pages run their JavaScript before the visitor arrives. MDN warns against speculating on URLs with side effects, such as logout or add-to-cart, and recommends delaying analytics and ad code with document.prerendering. Servers can recognize speculative requests by the Sec-Purpose header.

Sources

Speculation Rules API – MDN Web Docsdeveloper.mozilla.org
Guide to implementing speculation rules for more complex sites – Chrome for Developersdeveloper.chrome.com
Speculative loading – WHATWG HTML Standardhtml.spec.whatwg.org

Last updated: October 7, 2026