What is the Speculation Rules API?

The Speculation Rules API is a Chrome browser mechanism for anticipating the next page a user is going to visit and starting to prepare it before they click. The idea itself is not new, preloading resources has existed for years with rel=prefetch and rel=preload, but its scope is: instead of preloading a single file, it can prepare the whole navigation, including running JavaScript.

It replaces the old link rel=prerender tag, which Chrome retired because of its poorly controlled resource cost. The new API defines rules through a script type=speculationrules block in JSON format, which lets you specify precisely when to act: a fixed list of URLs, or a pattern that applies to any link meeting a condition, what the specification calls document rules.

It is a feature specific to Chromium-based browsers; as of this writing it is not a universal standard supported by every browser. In other browsers, the page still loads the usual way, without the head start this API provides, which matters when reading any performance measurement.

The API distinguishes two actions. Prefetch downloads the target document and keeps it in memory, without executing or rendering it; it is the lighter option. Prerender goes further: it loads the whole page in a hidden tab, runs its JavaScript, and keeps it ready, so that when the user clicks, the browser only has to swap the visible tab for the one already prepared, with no perceptible load time.

When each action fires is controlled by the eagerness parameter, with four levels: immediate acts as soon as the browser sees the rule, eager triggers after minimal interaction, around 10 milliseconds of the mouse hovering the link on desktop, moderate waits for a clearer interaction, around 200 milliseconds, or the start of a touch on mobile, and conservative only acts once the user has already started pressing. The higher the eagerness, the faster the content arrives, but also the more requests get fired without real need.

Document rules let you define the criterion with CSS selectors or URL patterns (href_matches, selector_matches), instead of listing each link by hand, so the rule automatically applies to every link in a list or category as that list changes over time.

The feature shipped in Chrome 109, in January 2023; the eagerness parameter arrived in Chrome 121, and later versions (136, 138) have added further control, including the ability to specify which tab the result should activate in. Anyone using the technique should therefore also track the Chrome version in use, not just the rule itself.

When images are already compressed and the server responds quickly, the remaining room to improve LCP (Largest Contentful Paint) usually lies in the navigation itself: the time it takes the browser to start loading the next page after the click. Prerender can cut that time to practically zero, because the page was already loaded by the time the user clicked.

That is the technical explanation behind sites that «appear» without the usual loading flicker: it is not that the server is faster, it is that the browser started working before the click. For a site that has already exhausted its image and server optimisations, it is one of the few remaining levers to keep lowering LCP.

The cost is on the other side: every prerender consumes the visitor's bandwidth and CPU even if it never gets used, so applying it without criteria to long listings can load pages nobody will visit. That is why the eagerness parameter exists: so that cost is only paid when there is a reasonable signal that the user is actually going to click. Balancing speed against wasted resources is the core of any sensible configuration. Ignoring that trade-off means giving up either real speed or unnecessarily spent server capacity.

• Start with prefetch on long listings (internal search results, catalogues) and reserve prerender for the most predictable routes, such as the next step in a purchase funnel.
• Use eagerness moderate or conservative on less predictable links, and eager or immediate only where the next click is nearly certain, for example a next button in pagination.
• Don't apply prerender to pages with side effects on load, such as a purchase, a form submission, or an unwanted analytics event; the load happens even if the user never clicks.
• Measure the real impact on LCP with field data (CrUX), not only in the lab: behaviour changes depending on the visitor's device and connection.
• Check data usage on mobile devices with limited connections before activating broad rules based on lists or patterns (document rules).
• Check browser support before relying on this technique as your only performance improvement: as of this writing it is specific to Chromium-based browsers.

• Applying prerender to an entire results listing without filtering, which multiplies requests and can strain the visitor's connection without actually improving the experience.
• Confusing prefetch with prerender: prefetch does not execute JavaScript or render, so it does not offer the same speed jump and does not serve the same use case.
• Not checking that the destination page has no side effects on load, which can trigger unwanted actions before the actual click.
• Treating it as a substitute for optimising images or the server, when it is an additional lever that only pays off once those improvements are exhausted.
• Assuming it improves crawling or indexing: a search engine crawler does not navigate the way a user does in Chrome, so this technique does not change how the page is accessed from outside the browser, only the human visitor's experience.