# Speculation Rules API: prefetching and prerendering likely next pages

> How a <script type="speculationrules"> JSON block tells the browser which URLs to prefetch or prerender before the user navigates, the eagerness levels that control timing, and why support is Chromium-first — Safari only experimentally supports prefetch, and Firefox does not implement it at all.

**In one line:** The Speculation Rules API lets a page declare, in a JSON
`<script type="speculationrules">` block, which URLs the browser should prefetch or
prerender ahead of navigation; per MDN, a prerendered navigation can feel
near-instant, while prefetch only downloads the response body in advance to make
the eventual render faster.

## Declaring rules

A speculation rules block lists URLs (or a document-wide pattern) under a
`prerender` or `prefetch` action:

```html
<script type="speculationrules">
{
  "prerender": [
    {
      "urls": ["/next-page.html"]
    }
  ]
}
</script>
```

When the browser prerenders `/next-page.html`, per Chrome for Developers a navigation
to that URL is served from the already-rendered page instead of starting a fresh load.

## Eagerness

Per Chrome for Developers, each rule can set an `eagerness` of `"immediate"`,
`"eager"`, `"moderate"`, or `"conservative"`, controlling how soon the browser acts
on it. Unless a rule specifies otherwise, list (`"urls"`) rules default to
`"immediate"` and document (`"where"`) rules default to `"conservative"`:

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

Per Chrome for Developers, on desktop `"moderate"` triggers a speculation once the
pointer hovers a matching link for about 200ms (or on `pointerdown` if that happens
sooner); on mobile it instead uses viewport heuristics rather than hover or
pointerdown. `"conservative"` waits for pointer/touch down — the least speculative,
lowest-resource-cost option.

## Where it is supported

Per MDN's compatibility data, the Speculation Rules API is primarily a
Chromium-based feature (Chrome, Edge, and other Chromium-based browsers such as
Opera and Samsung Internet); Firefox does not implement it, and Safari 26.2 only
supports `prefetch` rules behind an experimental preference, with no `prerender`
support. A `<script
type="speculationrules">` block on an unsupported browser is inert markup — it is
simply ignored.

## Feature detection and fallback

```js
function supportsSpeculationRules() {
  return (
    typeof HTMLScriptElement.supports !== 'undefined' &&
    HTMLScriptElement.supports('speculationrules')
  );
}

if (supportsSpeculationRules()) {
  const script = document.createElement('script');
  script.type = 'speculationrules';
  script.textContent = JSON.stringify({
    prefetch: [{ urls: ['/next-page.html'] }],
  });
  document.head.append(script);
} else {
  // Unsupported: fall back to the older, more widely supported
  // <link rel="prefetch"> to still warm the cache for the next navigation.
  const link = document.createElement('link');
  link.rel = 'prefetch';
  link.href = '/next-page.html';
  document.head.append(link);
}
```

## Practical checklist

- [ ] Feature-detect with `HTMLScriptElement.supports('speculationrules')` before
      relying on it, and provide the older, more widely supported
      `<link rel="prefetch">` as a fallback for other engines.
- [ ] Prefer `prefetch` over `prerender` for pages you are only moderately confident
      the user will visit — per MDN, an unused prefetch still wastes network
      bandwidth and cache memory, but its upfront cost is smaller than an unused
      prerender's.
- [ ] Do not default every rule to `"immediate"` — per Chrome for Developers,
      immediate/eager rules keep the browser holding onto a limited number of
      prefetched/prerendered pages in memory at once.
- [ ] Remember this API has no effect on Firefox, and only limited experimental
      `prefetch` support on Safari; do not build a feature that depends on it for
      those browsers to function correctly.
- [ ] Re-check the eagerness default per rule type — list rules default to
      `"immediate"`, document rules default to `"conservative"`.

## Where to go next

- [Navigation preload](/reference/performance/navigation-preload/)
- [Core Web Vitals](/reference/performance/core-web-vitals/) — per Chrome for
  Developers, prerendering can improve LCP, CLS, and INP.