---
title: Speed up navigations with the Speculation Rules API
description: >-
Declare prefetch and prerender rules for likely next-page navigations to make
them near-instant for users by fetching or rendering target pages before the
click happens.
source_url:
html: >-
https://shopify.dev/docs/storefronts/themes/best-practices/performance/use-speculation-rules
md: >-
https://shopify.dev/docs/storefronts/themes/best-practices/performance/use-speculation-rules.md
api_name: liquid
---
# Speed up navigations with the Speculation Rules API
Use the [Speculation Rules API](https://developer.chrome.com/docs/web-platform/prerender-pages) to declare which links should be prefetched or prerendered for faster navigation.
***
## Why
Speculating on navigations is a trade-off between performance and resource consumption. If you prerender a page that the user never visits, then you've wasted their data and the browser's resources, which could have been used for the current page. Prerendering can also fire analytics events prematurely and lead to stale content if the user's state, such as the shopping cart, changes after a page is prerendered but before they navigate to it.
Since June 2025, Shopify has enabled a platform-wide Speculation Rules configuration for all Liquid storefronts. Shopify sends a `Speculation-Rules` HTTP header that points to a JSON file with rules. By default, Shopify uses `"prefetch"` with a `"conservative"` eagerness, so the browser prefetches when the user touches down on the screen or presses the mouse button.
In [Speculation Rules at Shopify](https://performance.shopify.com/blogs/blog/speculation-rules-at-shopify), we reported that this default configuration makes same-site navigations on Chromium roughly 220 ms faster at the median on desktop and roughly 20 ms faster on mobile. It adds only about 0.7% extra Storefront Renderer (SFR) traffic, and about 10% of all users get the HTML before navigation starts. Speculation rules are currently supported in Chromium-based browsers (Chrome, Edge, Opera). Safari and Firefox ignore `
```
Then add the `data-instant-navigation` attribute to any link you're confident the user is likely to click:
```liquid
View product
```
**Caution:**
Use `prerender` with caution. Be mindful of analytics events firing prematurely and of stale content issues. Shopify automatically sends a `Clear-Site-Data` header to clear prefetch and prerender caches when the cart is modified, but you might need to handle other state changes yourself.
***
## Examples
### Prefetch compared to prerender
* `"prefetch"`: fetches the response but doesn't render or execute code. Safer, with a lower resource cost.
* `"prerender"`: fetches and renders the page, including executing JavaScript. Higher resource cost, but faster navigation.
Rules can target URLs by list, pattern, or CSS selector. The `eagerness` setting controls how strong a signal the browser waits for before it acts.
### Eagerness values
From most to least aggressive:
* `"immediate"`: the browser speculates as soon as the rules are parsed, with no user interaction required. This prerenders every matching link on the page immediately, which can be expensive on collection pages with many product links.
* `"eager"`: the browser acts on even a slight signal, such as the cursor moving toward a link, a momentary hover, or a scroll pausing with the link prominent in the viewport.
* `"moderate"`: the browser acts when behavior suggests a likely navigation, such as the cursor resting over a link. In Chrome, this is a hover of roughly 200 ms.
* `"conservative"`: the browser acts on touchdown or mousedown, which is the moment closest to the click. Lowest resource cost.
If you omit `eagerness`, then document rules default to `"conservative"` and list rules default to `"immediate"`.
**Note:**
`"eager"` doesn't mean "speculate immediately". That's `"immediate"`, which was added when `"eager"` was redefined to sit between `"immediate"` and `"moderate"`.
### Conservative compared to moderate eagerness
Switching from `conservative` to `moderate` increases the prefetch rate by roughly 0.7 to 1.0 percentage points from a 12 to 14% baseline, which adds roughly 2 to 4% more SFR requests. `moderate` is the best trade-off for most themes: it speculates early enough to be useful, but doesn't waste resources on links the user never approaches.
***
## Testing
* Use the [Chrome DevTools Elements panel](https://developer.chrome.com/docs/devtools/dom) to inspect any `