Speculation Rules: prefetch and prerender
How the Speculation Rules API prefetches or prerenders the next page in Chrome: the JSON syntax, eagerness levels, limits, caveats and when not to use it.
· Updated · 4 min read

The Speculation Rules API lets a page tell Chrome which other pages to fetch or fully render in advance, so that a click feels instant. You write a small JSON block in a script tag, and the browser decides when to act on it. It is a progressive enhancement: browsers that do not support it ignore the block.
This guide follows Chrome's documentation on prerendering pages. I do not use speculation rules on this site yet, and I describe what I do use instead near the end.
Prefetch and prerender#
- Prefetch loads the document and keeps it in memory without rendering it. Chrome's guide says that, unlike
<link rel="prefetch">, it can fetch documents that the HTTP cache would not store. - Prerender goes further. The guide describes a prerender as behaving as if the page had been opened in an invisible background tab. When the visitor navigates to it, the browser swaps it in.
The syntax#
A list of URLs:
<script type="speculationrules">
{
"prerender": [{ "urls": ["next.html", "next2.html"] }]
}
</script>
Or document rules, which match links on the page:
<script type="speculationrules">
{
"prerender": [
{
"where": { "href_matches": "/*" },
"eagerness": "moderate"
}
]
}
</script>
Eagerness#
The eagerness value controls when the browser starts:
| Value | When it triggers |
|---|---|
immediate | As soon as the rules are seen. The default for URL lists. |
eager | On desktop, after a 10 ms hover. On mobile it uses viewport heuristics. |
moderate | On desktop, after a 200 ms hover or on pointer down. |
conservative | On pointer or touch down. The default for document rules. |
A lazier setting wastes less and is a little slower to pay off.
Support#
The documentation's badges list prerender in Chrome 109 and Edge 109, eagerness in Chrome 121 and Edge 121, and tags in Chrome 136 and Edge 136. It shows Firefox as not supported and Safari behind a flag. Check current tables before you rely on it, because this changes.
Caveats from the guide#
- Treat it as a hint and a progressive enhancement. The browser may ignore it.
- Prerendering uses extra memory and network bandwidth, so avoid speculating on too many pages. Over-speculation costs bandwidth, memory and CPU, for visitors and for your server.
- Chrome skips speculation under Save-Data, Energy Saver at low battery, memory pressure, when the "Preload pages" setting is off and in background tabs.
- There are limits: 50 immediate prefetches and 10 immediate prerenders. The eager, moderate and conservative settings allow two each, first in, first out.
- Intrusive APIs such as permission prompts are delayed until the page is activated, and if that is not possible the prerender is cancelled. Chrome does not render cross-origin iframes on a prerendered page until activation.
- Speculation rules inside a prerendered page only take effect after activation.
Analytics needs care too. A prerendered page loads in the background before the visitor sees it, so a tool may record a view early. The guide says Google Analytics, Google Publisher Tags and AdSense wait until the page is activated by default. The guide has a section on measuring performance with prerendering. I did not read that part, so check it before you trust your numbers.
When not to use it#
Prerendering a heavy page is a bad trade. My Ostra Tidal 41 example downloads hundreds of large frames, as I describe in Scroll image sequences on a budget. Rendering that page in the background would spend memory and bandwidth for a visit that may never happen. A cheap content page is a good candidate. A page full of side effects, such as one that logs out a user or counts a view, is not.
What I use on this site#
The site is a static Next.js export. The topic tiles on the home page and the topic, previous and next links on example pages use a small HoverLink component. The example cards in topic grids turn prefetch off entirely. It turns off the router's automatic prefetch and calls router.prefetch when the pointer enters the link, when it takes focus or on touch start:
const warm = () => {
if (href.startsWith("/")) router.prefetch(href);
};
The reason is that the default behaviour prefetches routes as links come into view, and a page with many example links would load many routes that nobody opens. Waiting for hover or focus ties the work to a stronger signal of interest. This is a framework prefetch of the next route's code, not a prerender of the finished page, and it only helps client-side navigation.
I have not measured whether speculation rules would improve navigation here.
Limits of this guide#
I read the first part of Chrome's documentation, up to the measuring section. The support list comes from the page's badges, and I did not check Firefox or Safari myself. I have not tried speculation rules on a real site.