The Speculation Rules API Explained

The Speculation Rules API is a browser feature that lets a page declare which links are likely to be visited next, so the browser can fetch — or even fully render — those pages in the background before the user clicks. Done well, a navigation that would normally take a few hundred milliseconds of network and render time instead feels instant, because the destination page was already built by the time the click happened.

It’s the modern successor to the old <link rel="prerender"> tag, redesigned with more control over when speculation happens and how much work the browser does ahead of time.

Prefetch vs prerender

Speculation rules support two distinct strategies, and the difference matters for both performance and cost:

• Prefetch downloads the destination page’s HTML response ahead of time and keeps it in a cache, so the navigation skips the network round trip. It’s cheap — no rendering or script execution happens until the user actually navigates.
• Prerender goes further: the browser loads the page, runs its JavaScript, and renders it in a hidden background tab. When the user clicks, the browser swaps to the already-rendered page instantly. It’s far more effective but also far more expensive, since it does the full work of loading a page speculatively.

This is a more aggressive version of the older resource hints — preload, prefetch, and preconnect — which fetch individual resources or warm up a connection but don’t fetch or render an entire alternate page.

Declaring speculation rules

Rules are declared with a <script type="speculationrules"> block containing JSON:

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

This tells the browser: any link matching /blog/* is a prerender candidate, and it should act with “moderate” eagerness. The eagerness field controls how aggressively the browser acts on a rule:

• immediate — start speculating as soon as the rule is seen, without waiting for user interaction.
• eager — speculate on pointerdown/hover with a short delay.
• moderate — the default; waits for a hover or touch that suggests real intent, with more of a delay than eager.
• conservative — only speculates once the user has clearly committed, such as on pointerdown.

Higher eagerness means faster perceived navigation but more wasted work when a user hovers without clicking. Picking eagerness per section of the site — conservative for expensive, rarely-visited pages, eager for the primary navigation flow — is usually the right trade-off.

What makes a page safe to prerender

Prerendering runs a page’s JavaScript before the user asked for it, which creates real hazards if a page assumes it’s always in an active, visible tab. Pages should avoid firing analytics events, mutating global state, or making side-effecting requests purely on load — logic tied to user intent belongs behind an interaction check, not a page load.

The browser also exposes the Page Lifecycle state so a prerendering page can detect it isn’t active yet and defer work like analytics pings until activation. Sites with login flows, one-time tokens, or non-idempotent GET requests should exclude those routes from speculation rules entirely, since a prerendered request that never becomes a real navigation can still trigger server-side side effects.

Speculation rules vs other performance techniques

	Speculation Rules (prerender)	Resource hints (preload/prefetch)	Service worker caching
What’s fetched	Entire page, HTML + assets	A single resource	Whatever you explicitly cache
Script execution	Yes, in background	No	No (unless intercepted and run)
Effort required	JSON rules, minimal code	A <link> tag per resource	A worker script and cache strategy
Best for	Anticipated next-click navigations	Known critical resources on the current page	Repeat visits, offline support

Speculation rules complement rather than replace techniques covered in a broader Core Web Vitals strategy — they specifically target the navigation itself, while things like image lazy-loading and critical CSS optimize the page once it’s already loading.

Relationship to view transitions

Speculation rules and the View Transitions API solve adjacent but different problems: one makes the destination page ready before the click, the other makes the visual switch between pages smooth once navigation happens. Used together, a prerendered page combined with a view transition can make a multi-page site feel closer to a single-page app’s instant, animated navigation — without adopting a client-side routing framework.

Browser support and fallback

As with most progressive-enhancement web platform features, browsers that don’t recognize speculationrules scripts simply ignore them — there’s no error, and navigation falls back to normal behavior. This makes the API low-risk to adopt: sites that support it get faster navigations, and sites that don’t fall through to the status quo unchanged.

The takeaway

The Speculation Rules API lets a site tell the browser which links are likely to be clicked next, so it can prefetch or fully prerender those pages ahead of time. Prefetch is cheap and just saves a network round trip; prerender does the full render in the background and makes navigation feel instant, at the cost of speculative work that may go unused. Scope rules carefully — exclude pages with side effects, tune eagerness to match how confident you are in the prediction, and treat it as a complement to resource hints and view transitions rather than a replacement for either.