Speculation Rules API

Definition

The Speculation Rules API is a browser API that lets developers declare rules for prerendering or prefetching pages a user is likely to navigate to next, using a JSON configuration rather than legacy per-link `<link rel=prefetch>` tags. It gives finer-grained control over which URLs to speculate on and under what conditions.

Overview

Browsers have long supported basic prefetching hints via `<link rel="prefetch">` and `<link rel="prerender">`, but these older mechanisms were limited — prefetch only fetched a resource without rendering it, and prerender (as originally implemented) had significant compatibility issues, resource costs, and lacked control over exactly when or under what conditions speculation should happen. The Speculation Rules API, introduced by Chrome, replaces these with a structured JSON format embedded in a `<script type="speculationrules">` block, letting developers specify a list of URLs or URL-matching patterns to prefetch or prerender, along with the conditions that should trigger it. A key feature is support for both explicit URL lists and 'document rules' that dynamically match links already present on the page (for example, prerendering any link matching a given CSS selector), plus eagerness settings (`immediate`, `eager`, `moderate`, `conservative`) that control how confident the browser should be before committing resources — for instance, only prerendering once the user's cursor hovers over or is likely about to click a link, rather than prerendering every link on the page indiscriminately, which would waste bandwidth and compute. Prerendering, specifically, goes further than prefetching: it doesn't just fetch the HTML but actually renders the destination page in a hidden, fully-functional browsing context, executing its JavaScript, so that when the user actually navigates, the transition is close to instantaneous, since the page is already fully loaded and rendered. Because aggressive prerendering can have real costs — wasted bandwidth for pages never visited, unwanted side effects if a prerendered page has analytics beacons or non-idempotent behavior firing before the user actually navigates — the API includes safeguards, and browsers restrict speculation to same-origin destinations by default (cross-origin prerendering requires an explicit opt-in on the target page). The Speculation Rules API matters for perceived web performance because it can make next-page navigations feel instantaneous without a full single-page-app client-side router, directly benefiting traditional multi-page sites that want SPA-like navigation speed while keeping the simplicity of standard page loads.

Specification

• Declares prefetch/prerender rules via a JSON `<script type="speculationrules">` block
• Supports explicit URL lists and dynamic document rules matching page links
• Eagerness settings control how confident the browser must be before speculating
• Prerendering fully renders a page (including JavaScript execution) in a hidden context
• Replaces legacy `<link rel=prefetch/prerender>` tags with finer-grained control
• Same-origin destinations by default; cross-origin prerendering requires target opt-in
• Can make next-page navigation feel near-instantaneous without a client-side router
• Chrome-led feature with growing adoption across the web performance ecosystem

Use Cases

Alternatives

History

The Speculation Rules API is a web-platform feature that lets a site declaratively tell the browser which future navigations to prefetch or fully prerender, delivering much faster — often instant — page loads. Rules are expressed as JSON and can list specific URLs or use "document rules" that match links automatically by URL pattern or CSS selector, with an "eagerness" setting to balance speculation against resource use. The API became available in Chrome and Edge starting with version 109 in January 2023, but it was the addition of document rules and eagerness controls in version 121 in early 2024 that made it broadly practical. It has since seen large-scale adoption, including by Cloudflare and WordPress, and is specified within the WHATWG HTML standard.

Frequently Asked Questions

Related in Web