Instant Page Loads with the Speculation Rules API

This article explores how the Speculation Rules API in Chromium-based browsers achieves near-instantaneous page loads. By utilizing declarative JSON structures, developers can instruct the browser to proactively prefetch or fully prerender target web pages in the background before a user clicks a link. Below, you will learn the core mechanics of this API, the differences between prefetching and prerendering, how to implement the code, and how the browser manages system resources during background rendering.

What is the Speculation Rules API?

The Speculation Rules API is a JSON-based syntax defined within a <script type="speculationrules"> tag. It replaces older, less reliable hints like <link rel="prerender">. Instead of guessing which link a user might click next, the API allows developers to explicitly define rules that tell the Chromium browser which outgoing URLs should be prepared in the background.

When a user finally clicks a speculated link, the browser simply swaps the current view with the pre-loaded background view, resulting in a zero-latency navigation experience.

Prefetching vs. Prerendering

The API enables instant loading through two distinct background mechanisms:

• Prefetching: The browser downloads the raw HTML document of the target URL and stores it in the memory cache. It does not download subresources (like images, CSS, or JavaScript) or execute any code. This uses minimal bandwidth and CPU while completely eliminating the network wait time for the initial document request.
• Prerendering: The browser downloads the HTML document, fetches all necessary subresources, executes JavaScript, and builds the entire Document Object Model (DOM) in an invisible background tab. When the user clicks the link, the hidden tab is instantly activated, making the page load appear instantaneous.

How to Implement Speculation Rules

To use the API, you insert a script tag with the type set to speculationrules into your HTML document's <head> or <body>. There are two main ways to define targets: URL Lists and Document Rules.

1. URL Lists

You can specify an exact array of URLs that the browser should prefetch or prerender. This is ideal when analytics show a high probability that the user will visit a specific next page.

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

2. Document Rules

Instead of hardcoding URLs, you can instruct the browser to scan the current document for links matching specific CSS selectors or URL patterns.

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

Controlling Triggers with Eagerness

Prerendering every link on a page would quickly exhaust a user's bandwidth and memory. To prevent this, Chromium uses the eagerness setting to combine developer rules with user interaction signals:

• immediate: The browser speculates as soon as it parses the rule, without waiting for user action.
• eager: Currently behaves like immediate, though future Chromium updates may trigger this when the user moves their cursor toward a link.
• moderate: The browser triggers the speculation when the user hovers over a link for 200 milliseconds (or on the pointerdown event on mobile devices).
• conservative: The browser waits until the user actively touches or clicks down on the link (pointerdown or mousedown), giving the browser a roughly 100-millisecond head start before the click completes.

Chromium's Built-In Safeguards

To ensure background prerendering does not degrade the user's current browsing experience or cause unintended side effects, Chromium enforces strict operational limits:

• Resource Limits: Chromium caps the number of concurrent prerenders (typically up to 10 for immediate/eager and 2 for moderate/conservative on a first-in, first-out basis).
• Deferred APIs: Features that would confuse the user if triggered in the background—such as auto-playing video/audio, WebRTC requests, geolocation prompts, and notifications—are automatically paused until the user actually clicks the link and activates the page.
• System Conditions: If the user has "Energy Saver" or "Data Saver" enabled, or if the device is low on memory, Chromium will automatically ignore speculation rules to preserve system health.