Speculation Rules API
The Speculation Rules API is a browser API that lets developers declare rules for prerendering or prefetching pages a user is likely to navigate to next, using a JSON configuration rather than legacy per-link `<link rel=prefetch>` tags. It…
Definition
The Speculation Rules API is a browser API that lets developers declare rules for prerendering or prefetching pages a user is likely to navigate to next, using a JSON configuration rather than legacy per-link `<link rel=prefetch>` tags. It gives finer-grained control over which URLs to speculate on and under what conditions.
Overview
Browsers have long supported basic prefetching hints via `<link rel="prefetch">` and `<link rel="prerender">`, but these older mechanisms were limited — prefetch only fetched a resource without rendering it, and prerender (as originally implemented) had significant compatibility issues, resource costs, and lacked control over exactly when or under what conditions speculation should happen. The Speculation Rules API, introduced by Chrome, replaces these with a structured JSON format embedded in a `<script type="speculationrules">` block, letting developers specify a list of URLs or URL-matching patterns to prefetch or prerender, along with the conditions that should trigger it. A key feature is support for both explicit URL lists and 'document rules' that dynamically match links already present on the page (for example, prerendering any link matching a given CSS selector), plus eagerness settings (`immediate`, `eager`, `moderate`, `conservative`) that control how confident the browser should be before committing resources — for instance, only prerendering once the user's cursor hovers over or is likely about to click a link, rather than prerendering every link on the page indiscriminately, which would waste bandwidth and compute. Prerendering, specifically, goes further than prefetching: it doesn't just fetch the HTML but actually renders the destination page in a hidden, fully-functional browsing context, executing its JavaScript, so that when the user actually navigates, the transition is close to instantaneous, since the page is already fully loaded and rendered. Because aggressive prerendering can have real costs — wasted bandwidth for pages never visited, unwanted side effects if a prerendered page has analytics beacons or non-idempotent behavior firing before the user actually navigates — the API includes safeguards, and browsers restrict speculation to same-origin destinations by default (cross-origin prerendering requires an explicit opt-in on the target page). The Speculation Rules API matters for perceived web performance because it can make next-page navigations feel instantaneous without a full single-page-app client-side router, directly benefiting traditional multi-page sites that want SPA-like navigation speed while keeping the simplicity of standard page loads.
Specification
- Declares prefetch/prerender rules via a JSON `<script type="speculationrules">` block
- Supports explicit URL lists and dynamic document rules matching page links
- Eagerness settings control how confident the browser must be before speculating
- Prerendering fully renders a page (including JavaScript execution) in a hidden context
- Replaces legacy `<link rel=prefetch/prerender>` tags with finer-grained control
- Same-origin destinations by default; cross-origin prerendering requires target opt-in
- Can make next-page navigation feel near-instantaneous without a client-side router
- Chrome-led feature with growing adoption across the web performance ecosystem
Use Cases
Alternatives
History
The Speculation Rules API is a web-platform feature that lets a site declaratively tell the browser which future navigations to prefetch or fully prerender, delivering much faster — often instant — page loads. Rules are expressed as JSON and can list specific URLs or use "document rules" that match links automatically by URL pattern or CSS selector, with an "eagerness" setting to balance speculation against resource use. The API became available in Chrome and Edge starting with version 109 in January 2023, but it was the addition of document rules and eagerness controls in version 121 in early 2024 that made it broadly practical. It has since seen large-scale adoption, including by Cloudflare and WordPress, and is specified within the WHATWG HTML standard.
Sources
- Chrome for Developers — Prerender pages for instant page navigations · as of 2026-07-17
- MDN Web Docs — Speculation Rules API · as of 2026-07-17
Frequently Asked Questions
From the Blog
Network Protocols Explained: The Rules Behind the Internet
Network protocols are the agreed-upon rules that let devices exchange data reliably across a network. This guide explains what protocols are, the major ones you'll encounter, and how they fit together in everyday communication.
Read More Data ScienceNumPy broadcasting: the rules, and the shapes that silently do the wrong thing
Broadcasting aligns array shapes from the trailing axis, stretching any axis of length one. The rule is short; the danger is the case it does not reject — a row vector against a column vector produces a full matrix where you wanted elementwise arithmetic, and every downstream number is wrong without an error.
Read More ProgrammingJavaScript this explained: binding rules and arrow functions
The value of this is determined by how a function is called, not where it is written — with one exception, arrow functions, which capture it from the enclosing scope. Apply the call-site rules in priority order and every this-is-undefined bug becomes a mechanical diagnosis rather than a guess.
Read More ProgrammingPractical rules for naming variables, functions and classes
Good names carry what the type cannot show: units, direction, nullability and lifecycle. This article turns naming from taste into a small set of decidable rules you can apply in review, plus why renaming is the cheapest refactor available to you.
Read More