Speculation Rules API: What It Is, How It Works & How It Boosts Website Speed

Website speed is no longer just a user experience concern, it is a core ranking signal that determines search visibility, conversions, and revenue. Enter the Speculation Rules API, a modern browser-native technology that makes page navigation feel near-instant by fetching or fully rendering likely next pages in the background before the user even clicks a link. Originally introduced by Google Chrome, this API is rapidly becoming one of the most powerful performance optimization tools available to web developers in 2025 and 2026.

What Is the Speculation Rules API?

The Speculation Rules API is a browser API designed to improve performance for future page navigations. It works by allowing developers to define structured rules, written in JSON, that tell the browser which pages a user is likely to visit next, so the browser can begin loading those pages in the background before any click occurs.

The API was created as a modern, more expressive replacement for the older and now deprecated > tag, as well as an enhancement over the basic > mechanism. Unlike its predecessors, the Speculation Rules API provides fine-grained control over:

• What to speculate (specific URLs or pattern-based document rules)
• How to speculate (prefetch vs. prerender)
• When to speculate (via eagerness levels)

The API is primarily designed for multi-page applications (MPAs), traditional websites where navigations involve full page loads, rather than single-page applications (SPAs) that manage routing internally. However, it can still benefit SPAs by prerendering the application initial state from a landing page.

How the Speculation Rules API Works

The Core Mechanism

When a browser encounters a <script type=”speculationrules”> block, it reads the JSON rules and begins speculatively loading the defined URLs in the background. If the user then navigates to one of those pre-loaded pages, the browser serves it from an in-memory cache, making the navigation feel essentially instantaneous.

The browser also listens to signals like mouse hover direction, pointer-down events, and link visibility to make smart decisions about when to trigger speculation, all governed by the eagerness setting defined in your rules.

Prefetch vs. Prerender: Two Levels of Speculation

The API supports two primary speculative loading strategies:

Strategy	What It Does	Resource Cost	Speed Benefit
Prefetch	Downloads the HTML response body of the target page, but does not render it or load subresources	Low (bandwidth only)	Moderate — faster TTFB
Prerender	Fully renders the page in a hidden background tab: fetches HTML, CSS, JS, images, and runs all JavaScript	High (CPU, RAM, bandwidth)	Maximum — near-zero LCP

Prefetching is a lightweight operation. The HTML document is downloaded and stored in the browser’s in-memory cache. When navigated to, the page renders faster since the server round-trip is eliminated, but rendering still happens at navigation time. Site monitoring performance has measured a p75 TTFB of just 45ms for prefetched pages.

Prerendering is far more powerful. The browser loads all subresources, executes JavaScript, and fully renders the page into an invisible tab. When the user navigates, the pre-rendered page is simply swapped into view, making the load feel instant. Sites using prerendering through this API have measured a p75 LCP of just 320ms, compared to 1,800ms for standard navigations, an 82% improvement.

The JSON Syntax: How to Write Specification Rules

Speculation rules are defined inside an inline <script type=”speculationrules”> block or via an HTTP response header pointing to an external JSON file. Here is a foundational example:

<script type="speculationrules">
{
  "prefetch": [
    {
      "urls": ["next.html", "next2.html"],
      "eagerness": "eager"
    }
  ],
  "prerender": [
    {
      "where": {
        "and": [
          { "href_matches": "/*" },
          { "not": { "href_matches": "/logout" } },
          { "not": { "href_matches": "/?*add-to-cart=*" } }
        ]
      },
      "eagerness": "moderate"
    }
  ]
}
</script>

The two core rule types are: – List rules ("urls": [...]): Target specific, known URLs, ideal when you know exactly which page comes next. – Document rules ("where": {...}): Use URL patterns or CSS selectors to dynamically target links on the page, ideal for broad site-wide speculation.

Eagerness Levels: Controlling When Speculation Fires

The eagerness property is the key knob for balancing performance gains against resource waste. There are four levels:

Eagerness Level	Trigger Condition	Best For	Default For
immediate	Fires as soon as rules are parsed	Known high-value next pages	List rules
eager	Identical to immediate (future differentiation planned)	Confirmed user paths	List rules
moderate	Fires after ~200ms hover on a link, or pointerdown on mobile	Balanced use cases	—
conservative	Fires only on pointerdown or touchstart	Low-confidence predictions	Document rules

With immediate eagerness, Chrome allows up to 50 prefetch and 10 prerender speculations simultaneously. With moderate or conservative, the limit is 2 speculations per eagerness level, using a first-in-first-out queue. The browser also automatically disables speculation entirely when the user has enabled Data Saver, is in Energy Saver mode on low battery, has insufficient memory, or has disabled the “Preload pages” browser setting.

How the Speculation Rules API Improves Website Speed

Near-Zero LCP for Prerendered Pages

The most dramatic performance benefit of the Speculation Rules API is its impact on Largest Contentful Paint (LCP), Google primary loading performance metric. By prerendering pages before the user clicks, the browser eliminates the network request, HTML parsing, resource loading, and rendering pipeline from the navigation critical path. A Chrome developer article notes that prerendering can deliver near-zero LCP, reduced CLS, and improved INP.

Real-World Performance Gains

The improvements seen in production deployments are significant:

• Cloudflare Speed Brain: Cloudflare deployed Speculation Rules across tens of millions of domains through its “Speed Brain” feature, measuring an average 40–50% improvement in LCP at the 75th percentile (p75).
• Google Search: Google uses the API to prefetch the first two organic search results. This reduced LCP for Chrome for Android users by 67ms and for desktop Chrome users by 58.6ms.
• Shopify: After deploying platform-wide Speculation Rules in June 2025, Shopify reported stores becoming up to 180ms faster across all loading metrics in supported scenarios.

Core Web Vitals Improvement

Because Google uses Core Web Vitals as a page experience ranking signal, Speculation Rules has direct SEO implications. The improvements translate across multiple CWV metrics:

• LCP: Dramatically reduced, often reaching the “Good” threshold of under 2.5 seconds effortlessly.
• INP (Interaction to Next Paint): Reduced since the background-rendered page responds immediately.
• CLS (Cumulative Layout Shift): Improved because resources are fully loaded before navigation completes.

Web.dev Core Web Vitals guidance explicitly identifies the Speculation Rules API as “another effective way to dramatically improve LCP performance”.

Implementing Speculation Rules: Step-by-Step Guide

Method 1: Inline Script Tag (Simplest)

Add this block inside your <head> or at the bottom of <body>:

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

This rule tells Chrome to prerender any same-origin page link when the user hovers over it for ~200ms.

Method 2: HTTP Response Header (Recommended for Dynamic Sites)

Serve a Speculation-Rules HTTP header that points to an external JSON file:

Speculation-Rules: “/speculation-rules.json“

Your speculation-rules.json file contains the same JSON structure. External files must be served with Access-Control-Allow-Origin headers if hosted on a CDN. This method is preferred because it keeps your HTML clean and allows you to update rules without touching page templates.

Method 3: WordPress Plugin

WordPress 6.8 merged core Speculative Loading support, which prefetches with conservative eagerness by default. For a more aggressive configuration, install the Speculative Loading plugin from WordPress.org, which defaults to prerendering with moderate eagerness and provides a UI under Settings > Reading to adjust mode and eagerness without editing code.

Method 4: Dynamic JavaScript Injection

For SPAs, e-commerce sites, or dynamically changing pages, use JavaScript to inject or refresh speculation rules based on user behavior or page content:

async function refreshSpeculations() {
  const speculationScripts = document.querySelectorAll('script[type="speculationrules"]');
  for (const speculationScript of speculationScripts) {
    const ruleSet = speculationScript.textContent;
    speculationScript.remove();
    await Promise.resolve(); // allow browser to cancel speculations
    const newScript = document.createElement('script');
    newScript.type = 'speculationrules';
    newScript.textContent = ruleSet;
    document.body.appendChild(newScript);
  }
}

This pattern is useful when the page state changes, for example, after a user filters products, and the previously speculated pages are no longer the most likely next destinations.

Safe Speculation: What to Avoid

Applying speculation rules without guardrails can cause unintended side effects. Always exclude URLs that perform server-side actions when visited:

{
  "prerender": [{
    "where": {
      "and": [
        { "href_matches": "/*" },
        { "not": { "href_matches": "/logout" } },
        { "not": { "href_matches": "/cart?*add-to-cart=*" } },
        { "not": { "selector_matches": ".no-prerender" } },
        { "not": { "selector_matches": "[rel~=nofollow]" } }
      ]
    },
    "eagerness": "moderate"
  }]
}

You can also add the no-prerender CSS class to individual <a> tags to exclude specific links from prerendering.

Speculation Rules API and SEO

One of the most compelling reasons to implement the Speculation Rules API is its indirect but measurable SEO impact. Google has incorporated Core Web Vitals into its Page Experience ranking signals since May 2021, and these signals continue to grow in importance. By dramatically improving LCP, the most heavily weighted CWV metric, through prerendering, sites can gain a competitive ranking edge.

Key SEO benefits include:

• Faster perceived page speed that improves Google PageSpeed Insights and CrWUX scores.
• Lower bounce rates due to instant-feeling navigation, increasing dwell time signals.
• Higher crawl efficiency on subsequent visits, as popular linked pages are already optimized for speed.
• Alignment with Google own practices, Google Search itself now uses the Speculation Rules API for its own results.
• Since Google increasingly values UX performance through Core Web Vitals, this API can positively influence SEO, provided it is used correctly and excludes unsafe pages.

Browser Support and Compatibility

The Speculation Rules API has growing but still limited cross-browser support as of early 2026:

Browser	Support Status
Chrome 109+	✅ Full support
Edge 109+	✅ Full support
Opera 108+	✅ Full support
Safari	⚠️ Working implementation, not enabled by default
Firefox	❌ Not yet supported

Browsers that do not support the API will silently ignore the <script type="speculationrules"> block with no errors or negative effects. This means implementation is safe as a progressive enhancement; unsupported browsers simply skip it, while Chromium-based browsers (which represent the majority of desktop and Android traffic) benefit fully.

For Firefox and Safari users, consider combining Speculation Rules with the traditional > as a fallback for critical page-to-page links.

Advanced Use Cases

E-Commerce: Prerender the Product Detail Page

For online stores, the highest-value speculation is prerendering product pages when a user hovers over a product listing card:

{
  "prerender": [{
    "where": {
      "and": [
        { "href_matches": "/products/*" },
        { "not": { "href_matches": "/cart*" } }
      ]
    },
    "eagerness": "moderate"
  }],
  "prefetch": [{
    "where": { "href_matches": "/cart" },
    "eagerness": "conservative"
  }]
}

Blog / Documentation: Prefetch Listed Articles

For content sites, prefetch the first 3–5 articles listed on a page using list rules with eager eagerness:

{
  "prefetch": [{
    "urls": ["/blog/post-1", "/blog/post-2", "/blog/post-3"],
    "eagerness": "eager"
  }]
}

Multi-Step Funnel: Prerender the Next Step

For landing pages with a clear user journey (e.g., a form wizard), prerender the next step immediately:

{
  "prerender": [{
    "urls": ["/step-2"],
    "eagerness": "immediate"
  }]
}

Key Limitations and Trade-Offs

Despite its power, the Speculation Rules API comes with important trade-offs that developers must consider:

1. Resource consumption: Prerendering is expensive. Speculating on pages the user never visits wastes CPU, RAM, and bandwidth on both client and server.
2. Server load: Each prerender triggers full page execution on the server. High-traffic sites may see increased server costs without careful scoping.
3. Analytics skew: Prerendered pages may fire analytics pageviews before the user actually navigates, inflating session data. Use the prerendering change event to defer analytics firing.
4. Stale content: Pages prerendered with immediate or eager eagerness may become outdated if content changes between speculation and navigation.
5. Cross-origin restrictions: Cross-site prerendering requires the destination to explicitly opt in with Supports-Loading-Mode: credentialed-prerender response header.
6. Deferred APIs: During prerender, sensitive APIs like Geolocation, Notifications, WebRTC, and Fullscreen are deferred until the page is actually navigated to (“activated”).

Best Practices for Maximum Performance

To get the most out of the Speculation Rules API while avoiding pitfalls, follow these guidelines:

• Start conservative, scale up: Begin with conservative prefetch, measure impact, then graduate to moderate prerender for high-traffic pages.
• Use analytics data: Let your real user analytics data guide which pages to speculate. Pages with the highest click probability from a given entry point are the best candidates.
• Exclude dangerous URLs: Always exclude logout, add-to-cart, form submission, and other stateful GET request URLs.
• Monitor Core Web Vitals: Use Real User Monitoring (RUM) tools to measure LCP improvement on prerendered navigations vs. standard navigations.
• Test with Chrome DevTools: The Application panel in Chrome DevTools includes a “Preloading & Prerendering” section to inspect active speculation rules and their status.
• Use document rules with moderate for broad sites: Rather than manually listing URLs, let the browser target links matching a pattern and only prefetch when the user shows intent by hovering.

Conclusion

The Speculation Rules API represents a fundamental shift in how browsers approach page navigation, moving from reactive loading to proactive, predictive loading. By telling the browser which pages users are likely to visit next, developers can reduce LCP to near-zero, improve all Core Web Vitals metrics, and deliver app-like navigation speeds on traditional multi-page websites.

With Cloudflare deploying it across tens of millions of domains (achieving 45% LCP improvement), Google Search using it natively to speed up organic result clicks, and Shopify rolling it out platform-wide in 2025, the Speculation Rules API has moved firmly from experimental feature to production-ready standard. For SEO professionals, content marketers, and web developers alike, implementing this API is one of the highest-ROI performance optimizations available today.

About the writer

Hassan Tahir wrote this article, drawing on his experience to clarify WordPress concepts and enhance developer understanding. Through his work, he aims to help both beginners and professionals refine their skills and tackle WordPress projects with greater confidence.