Speculation Rules API: Predictive Prerendering for Seamless Navigation

1. What is the Speculation Rules API

The Speculation Rules API is a declarative browser interface that lets a website tell the browser which follow-up pages the user is most likely to visit next. Rules are embedded as a JSON object inside a <script type="speculationrules"> element, so no extra JavaScript library is required. The browser evaluates these rules on its own and decides, based on signals like cursor movement or touch, when to actually act on them.

At its core the API distinguishes two actions: prefetch, which simply downloads the HTML document into the HTTP cache, and prerender, which fully renders the target page in a hidden, inactive process. The latter includes running JavaScript, loading subresources, and completing the entire page build. When the user actually clicks the predicted link, the browser just swaps in the already-finished state, cutting the perceived page transition down to a few milliseconds.

2. Difference to classic <link rel="prefetch">

The well-known <link rel="prefetch"> only loads the raw bytes of a resource, usually the HTML document, into the browser cache. No rendering, no DOM parsing, and no JavaScript execution happens at that point. When the actual navigation occurs, the browser still has to do the full rendering work, so while the network roundtrip is skipped, a noticeable chunk of load time remains.

Prerendering through the Speculation Rules API goes much further, since it fully builds the target page ahead of time, including layout, style computation, and script execution. As a result the navigation doesn't feel like loading at all to the user, it feels like switching between two already-finished states. This approach effectively replaces Chrome's earlier experimental NoState Prefetch technique as well as the deprecated <link rel="prerender"> directive entirely.

3. Eagerness Levels: Eager vs. Moderate in Practice

The eagerness setting controls how aggressively the browser triggers a rule. The immediate level starts speculation as soon as the rule is parsed, while eager reacts already on the first pointer movement near a link. The moderate level waits for roughly a two hundred millisecond hover or a pointerdown event, and conservative only fires on an actual pointerdown, right before the click completes.

For most online stores a middle ground works best: category and product listing links get moderate so only genuine purchase intent triggers a prerender, while especially important conversion paths such as the add-to-cart button can safely use eager. The example below shows a practical configuration with mixed eagerness levels for different URL patterns.

<script type="speculationrules">
{
  "prerender": [
    {
      "source": "document",
      "where": { "href_matches": "/checkout/cart*" },
      "eagerness": "eager"
    },
    {
      "source": "document",
      "where": { "href_matches": "/product/*" },
      "eagerness": "moderate"
    }
  ],
  "prefetch": [
    {
      "source": "document",
      "where": { "href_matches": "/category/*" },
      "eagerness": "conservative"
    }
  ]
}
</script>

4. Document Rules vs. List Rules

With source: "document", the browser continuously evaluates all links in the current document and automatically applies patterns defined in the where field, such as href_matches, to new links that appear later, for example after an AJAX update. This approach works great for category and search result pages whose link structure changes dynamically, without ever having to update the rules manually.

The alternative, source: "list", provides a fixed list of concrete URLs to speculatively load, independent of the visible links on the page. This is useful for known high-traffic targets such as the next step of a checkout flow, or a frequently visited landing page that may not even be linked from the current document. Both source types can be combined within the same rule set.

5. Browser Support and a Gradual Rollout

The Speculation Rules API is currently supported by Chromium-based browsers such as Chrome and Edge, while Firefox and Safari have not implemented it yet. Since the rules are embedded as plain JSON, non-supporting browsers simply ignore the element, so no errors occur and the page continues to work normally without prerendering. An explicit feature test isn't strictly necessary, though it doesn't hurt as extra insurance for monitoring purposes.

For a production rollout, a staged approach works best: start with prefetch at conservative eagerness for a small set of page types, observe the impact on load times and server load, and only then move selected sections to prerender. That way the effect can be measured with real user data before the rules are expanded across the entire site.

6. Server-Side Considerations and Headers

When the browser makes a speculative request, it sends the Sec-Purpose header with a value of either prefetch or prefetch;prerender. Server-side logic can inspect this header to, for instance, delay firing tracking pixels or analytics events until the actual, non-speculative request arrives. Without this distinction, page views would get double counted whenever a user ultimately never visits a predicted page.

There is also the No-Vary-Search header, which tells the browser that certain query parameters, such as tracking codes in the URL, have no effect on the page content. This allows an already speculatively loaded document to be reused even when the actually requested URL differs only in those unimportant parameters, noticeably improving cache hit rates.

7. Risks of Mispredictions

The biggest downside of an overly aggressive rule set is unnecessary server load from requests that never turn into an actual navigation. If every product card on a listing page is tagged with eager eagerness, for example, merely moving the mouse across the page can trigger dozens of speculative requests, most of which get discarded. This burdens the server infrastructure and also wastes bandwidth for users on limited data plans.

A second risk concerns pages with state changes: per specification, speculation rules may only apply to GET requests without form submission, so accidentally triggering destructive actions is technically ruled out. Still, server-side side effects such as incrementing view counters or populating session-dependent caches can be triggered by speculative requests if the backend fails to honor the Sec-Purpose distinction. A careful review of all affected endpoints is therefore mandatory before going to production.

8. A Practical Implementation Strategy

The most sensible starting point is measuring current navigation times with the Navigation Timing API, so a solid baseline exists before Speculation Rules are enabled. From there it pays off to start with a small, clearly scoped rule, for example only for the most frequently clicked category links, and observe the effect through real field data rather than relying solely on lab measurements.

In parallel, the backend team should verify that analytics events correctly distinguish speculative from real requests, and that expensive database operations on GET endpoints don't have unwanted side effects. Only once these fundamentals are in place does it make sense to gradually expand to more page types and fine-tune eagerness values based on the measured conversion probability of each link group.

9. Summary and Outlook

The Speculation Rules API shifts part of a website's load time away from the moment of the click into the time before it, while the user is still reading or deciding anyway. Configured correctly, this creates a navigation experience that feels like a single-page application to the user, even though classic multi-page navigation is still happening under the hood. That closes an important gap between traditional websites and modern app-like experiences.

Looking ahead, more browser vendors are likely to adopt the API, and it is expected to gain finer controls for cross-origin prerendering over time. Until then it remains a progressive enhancement that speeds up supporting browsers without affecting other browsers in any way, making it a low-risk but high-impact building block of modern performance strategies.

10. Zusammenfassung

11. FAQ: Speculation Rules API