What is the Speculation Rules API?

It is a way to tell the browser, in a small block of JSON, which pages a visitor is likely to navigate to next - so the browser can fetch or even fully render them in advance. When the visitor does click, the page is already there and the navigation feels instant. It replaces the older approach with something more expressive: you can match URLs by pattern, and you can choose how eager the browser should be.

What is the difference between prefetch and prerender?

Prefetch downloads the document but does nothing with it. Prerender goes much further: it builds the page in a hidden tab, runs its JavaScript and fires its requests. Prerender gives the more dramatic result and costs far more - it is a full page load for a visit that may never happen. Start with prefetch, and reserve prerender for the one or two destinations you are genuinely confident about.

What do the eagerness settings do?

Eagerness tells the browser when to act on a rule. 'immediate' acts as soon as the rules are parsed, 'eager' close to it, 'moderate' waits for a hover of roughly 200 ms, and 'conservative' waits for the pointer or touch to actually go down on the link. Moderate and conservative are the ones that respect a visitor's data: they only speculate once there is a real signal of intent.

Is it safe to prerender any page?

No, and this is the part worth reading twice. A prerendered page runs as though it had been visited, so anything with a side effect is dangerous: logout links, one-click actions, endpoints that record a view or consume a token. Analytics also need care, or you will count visits that never happened. Restrict speculation to safe, idempotent destinations.

The Speculation Rules API: prerendering the next page, and the bill that comes with it

Q: Which browsers support Speculation Rules?

Support is strongest in Chromium-based browsers, where the API originated and where prerendering is most complete. Other engines have been more cautious, and support differs between prefetch and prerender rather than being a single yes or no. Treat it as a progressive enhancement: browsers that do not understand the rules simply ignore the script block, and everyone still gets a working site.

The Speculation Rules API lets you tell the browser which page a visitor will probably open next, so it can be fetched - or fully built - before they click. Done well, the next navigation appears to take no time at all. Done carelessly, you are downloading whole pages for people who were never going to visit them.

Both halves of that sentence matter, and most introductions only cover the first.

What it looks like

Rules go in a script block, as JSON:

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

That says: when a visitor shows real interest in any link under /guides/, start building that page in the background. No <link> tags to maintain per destination, and the pattern does the work.

Prefetch or prerender: not a small difference

Prefetch downloads the document and stops there. It is cheap, and it removes the network round trip from the click.

Prerender builds the whole page in a hidden tab: it parses the HTML, applies the CSS, runs the JavaScript and lets that JavaScript make its own requests. The click then costs almost nothing, because the work is already done.

The cost follows the same ratio. A prerender is a complete page load, paid in advance, for a visit that may never occur - on someone's mobile data, on someone's battery. Prefetch is the sensible default; prerender is for the one destination you are genuinely sure about, like the first result on a search page.

A blurred view through a car windscreen on a road at night: the trees and sky are stretched outward by motion, the white lane markings rush toward the centre, and a few red and white vehicle lights sit far ahead

The road ahead seen from a moving car, everything at the edges smeared by motion, a few distant lights in the middle. Speculation is a bet on where someone is heading - and it is paid for whether or not the bet lands.

Eagerness: the setting that decides who pays

Four values, and the choice is really about how much you are willing to spend on a guess.

immediate - act as soon as the rules are parsed. No signal of intent at all.
eager - act on the slightest interaction.
moderate - wait for a hover of roughly 200 ms.
conservative - wait for pointer-down or touch-start, the moment just before the click.

Moderate and conservative are the two that respect the visitor, because they only spend data once a person has shown genuine intent. Immediate on a page of fifty links is how you turn one visit into fifty page loads.

The part that can break your site

A prerendered page runs. Its JavaScript executes, its requests fire, and it behaves as if it had been visited - because as far as it knows, it has been.

So anything with a side effect is a hazard: a logout link, a one-click action, an endpoint that increments a counter or burns a single-use token. Analytics deserve their own thought, or you will record visits that never took place; the Page Visibility API and the prerenderingchange event exist precisely to let a page hold that work back until it is genuinely shown.

Restrict speculation to destinations that are safe to load twice, and never to anything that changes state.

Should you use it?

Yes, with prefetch and moderate, on a site where the next click is reasonably predictable - documentation, articles, product listings, search results. That combination is close to free and the improvement is real.

Be much more careful with prerender, and think about who is paying for the guesses you get wrong. Browsers that do not understand the block ignore it entirely, so there is no fallback to write.

One honest note about support: it is strongest in Chromium-based browsers, where the API originated, and the picture differs between prefetch and prerender rather than being a single yes or no. Check current support for the specific one you use rather than trusting a summary - including this one.

If you want to know which modern features are actually deployed in the wild rather than merely supported, we measured eighteen of them across the Tranco top 600 and published the results and the raw data. Speculation Rules was not part of that run - so we have no first-hand figure for it, and we are not going to invent one.