How to Implement Speculation Rules API for Instant Page Loads

We’ve all been there: you click a link, and for a split second, there’s that dreaded white screen of death while the browser fetches the next document. In my experience building high-performance web apps, this is where you lose users. While we’ve used <link rel="prefetch"> for years, it’s a blunt instrument. That’s why I’m excited about the Speculation Rules API.

If you’re wondering how to implement Speculation Rules API, you’re looking at the modern way to achieve ‘instant’ navigation. Unlike older methods, this API allows you to define a JSON-based set of rules that tell the browser exactly when to prefetch or even fully prerender a page in a hidden background tab. When the user finally clicks, the page is already there. It’s the closest thing to a Single Page Application (SPA) feel for traditional multi-page sites.

Prerequisites

Before we dive into the code, ensure you have the following:

• A site served over HTTPS (Speculation Rules require a secure context).
• A modern Chromium-based browser (Chrome 110+).
• A basic understanding of how to inject scripts or HTML into your page templates.
• An awareness of your core web vitals optimization guide 2026, as prerendering directly impacts your LCP (Largest Contentful Paint).

Step-by-Step Implementation

Step 1: Defining the Speculation Rules

The API doesn’t use a JavaScript function call in the traditional sense; instead, it uses a <script type="speculationrules"> tag containing a JSON object. I recommend starting with a simple ‘prefetch’ rule to avoid overloading your server.

<script type="speculationrules">
{
  "prefetch": [
    { 
      "source": "list", 
      "urls": ["/about", "/contact", "/pricing"] 
    }
  ]
}
</script>

In this example, the browser will fetch the HTML for these three pages and store them in the HTTP cache. This is safe and low-bandwidth.

Step 2: Moving to Prerendering for Instant Loads

If you want that ‘instant’ feel, you need prerender. Prerendering goes beyond prefetching; it actually renders the page in an invisible background tab, executing JS and CSS. As shown in the image below, the difference in execution is massive.

<script type="speculationrules">
{
  "prerender": [
    { 
      "source": "document", 
      "where": { 
        "and": [
          { "document-url": "/blog" },
          { "selector": "a[href^='/blog/']" }
        ]
      }
    }
  ]
}
</script>

This rule tells the browser: “If the user is on the /blog page, prerender any link that points to a blog post.” This is incredibly powerful for content-heavy sites.

Step 3: Implementing Document-Based Rules

In my testing, the most efficient way to implement this is by using source: "document". This allows you to target specific links based on CSS selectors. For example, you can prerender the ‘Next’ button in a paginated series.

<script type="speculationrules">
{
  "prerender": [
    { 
      "source": "document", 
      "where": { 
        "selector": ".next-page-link" 
      }
    }
  ]
}
</script>

Pro Tips for Production

• Avoid Prerendering POST requests: The API only works for GET requests. Don’t try to prerender pages that trigger state changes.
• Watch your Server Load: Prerendering is essentially a full page visit. If you have 1,000 users and each prerenders 3 pages, your server sees 4,000 requests. Monitor your logs closely.
• Combine with Font Loading: Since prerendering loads the entire page, ensure you are optimizing font loading for LCP to prevent layout shifts when the prerendered page is finally swapped into view.
• Use the ‘Hover’ trigger: You can dynamically inject speculation rules via JS when a user hovers over a link for more than 200ms, reducing wasted bandwidth.

Troubleshooting Common Issues

If your rules aren’t working, check these common pitfalls:

What’s Next?

Once you’ve mastered the Speculation Rules API, the next step is fine-tuning your delivery. I recommend looking into edge computing (like Cloudflare Workers) to determine which rules to send based on the user’s device power and connection speed. Not every user on a 3G connection should be prerendering three pages at once.

Ready to boost your performance? Start by adding a simple prefetch list to your navigation menu today.