How Speculation Rules API Speeds Up Page Transitions

This article explores the Speculation Rules API, an advanced web platform feature designed to deliver near-instant page navigations through intelligent prefetching and prerendering. You will learn the core differences between traditional resource loading and full-page prerendering, how the API safely executes pages in the background, and how developers can implement these declarative rules to drastically reduce latency for end users.

The Evolution of Speculative Loading

Historically, developers relied on resource hints like <link rel="prefetch"> and <link rel="prerender"> to speed up future navigations. However, these mechanisms were rigid, offered little programmatic control, and were often resource-heavy or poorly supported by modern browsers.

The Speculation Rules API supersedes these legacy methods by introducing a flexible, JSON-based declarative syntax. Instead of merely downloading static assets, it allows browsers to selectively pre-render entire web pages—downloading the HTML, executing scripts, fetching subresources, and rendering the DOM in a hidden background context before a user clicks a link.

Prerendering vs. Prefetching

The Speculation Rules API supports two primary actions:

  • Prefetching: Downloads only the response body of the target HTML document. It does not execute JavaScript or fetch associated stylesheets, scripts, or images. This saves bandwidth while still offering a minor performance boost.
  • Prerendering: Downloads the target document, fetches all subresources, parses the CSS, builds the DOM tree, and runs JavaScript in an isolated, invisible environment. When the user navigates to the page, the browser swaps the pre-rendered page into the active tab instantly, achieving zero-latency navigation.

How Speculative Prerendering Accelerates Transitions

The fundamental reason the Speculation Rules API makes page transitions feel instantaneous is that it shifts the heavy lifting off the critical path of navigation.

  1. Background Processing: Under normal conditions, clicking a link triggers a DNS lookup, TCP/TLS handshake, time-to-first-byte (TTFB), DOM construction, and asset evaluation. With prerendering, all of these steps occur while the user is still interacting with the current page.
  2. Activation Instead of Navigation: When a user navigates to a prerendered URL, the browser performs an "activation" rather than a full fetch. The browser seamlessly presents the already-rendered page, bringing metrics like Largest Contentful Paint (LCP) and First Input Delay (FID) / Interaction to Next Paint (INP) down to near zero.
  3. Restricted Execution for Safety: To conserve battery, bandwidth, and system memory, modern browser implementations impose strict restrictions on prerendered contexts. Pages running in prerender cannot display intrusive interfaces, access media devices, or trigger notifications until activation occurs.

Syntax and Implementation

Speculation rules are injected directly into the HTML document using a specialized script element:

<script type="speculationrules">
{
  "prerender": [
    {
      "source": "list",
      "urls": ["/next-page.html", "/checkout/summary"]
    }
  ]
}
</script>

Developers can also define dynamic rules based on link patterns instead of hardcoded lists. Using document rules, the browser observes internal links and triggers speculative operations based on specific criteria or selectors:

<script type="speculationrules">
{
  "prerender": [
    {
      "source": "document",
      "where": {
        "and": [
          { "href_matches": "/*" },
          { "not": { "href_matches": "/logout" } },
          { "not": { "selector_matches": ".no-prerender" } }
        ]
      },
      "eagerness": "moderate"
    }
  ]
}
</script>

Smarter Resource Management with Eagerness Settings

To avoid wasting user data or bogging down CPU performance, speculation rules provide an eagerness property with four settings:

  • Immediate: Begins pre-rendering as soon as the rule is parsed, regardless of user behavior.
  • Eager: Similar to immediate, but allows the browser to apply minor heuristics before initiating the operation.
  • Moderate: Starts the speculative action when the user performs a clear intent-based action, such as hovering over or focusing on a link for 200 milliseconds.
  • Conservative: Triggers only on explicit interactions, such as pointerdown or mousedown, giving the browser just enough time to initialize the connection and start parsing before the click completes.

By combining the precision of document matching with fine-tuned eagerness thresholds, the Speculation Rules API allows web applications to deliver native-like, zero-latency transitions without exhausting client-side resources.