Skip to content

Prefetch

Page load times play a big role in the usability and overall enjoyment of a site. Astro’s opt-in prefetching brings the benefits of near-instant page navigations to your multi-page application (MPA) as your visitors interact with the site.

You can enable prefetching with the prefetch config:

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
prefetch: true
});

A prefetch script will be added to all pages of your site. You can then add the data-astro-prefetch attribute to any <a /> links on your site to opt-in to prefetching. When you hover over the link, the script will fetch the page in the background.

<a href="/about" data-astro-prefetch>

Note that prefetching only works for links within your site, and not external links.

The prefetch config also accepts an option object to further customize prefetching.

Astro supports 4 prefetch strategies for various use cases:

  • hover (default): Prefetch when you hover over or focus on the link.
  • tap: Prefetch just before you click on the link.
  • viewport: Prefetch as the links enter the viewport.
  • load: Prefetch all links on the page after the page is loaded.

You can specify a strategy for an individual link by passing it to the data-astro-prefetch attribute:

<a href="/about" data-astro-prefetch="tap">About</a>

Each strategy is fine-tuned to only prefetch when needed and save your users’ bandwidth. For example:

  • If a visitor is using data saver mode or has a slow connection, prefetch will fallback to the tap strategy.
  • Quickly hovering or scrolling over links will not prefetch them.

The default prefetch strategy when adding the data-astro-prefetch attribute is hover. To change it, you can configure prefetch.defaultStrategy in your astro.config.mjs file:

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
prefetch: {
defaultStrategy: 'viewport'
}
});

If you want to prefetch all links, including those without the data-astro-prefetch attribute, you can set prefetch.prefetchAll to true:

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
prefetch: {
prefetchAll: true
}
});

You can then opt-out of prefetching for individual links by setting data-astro-prefetch="false":

<a href="/about" data-astro-prefetch="false">About</a>

The default prefetch strategy for all links can be changed with prefetch.defaultStrategy as shown in the Default prefetch strategy section.

As some navigation might not always appear as <a /> links, you can also prefetch programmatically with the prefetch() API from the astro:prefetch module:

<button id="btn">Click me</button>
<script>
import { prefetch } from 'astro:prefetch';
const btn = document.getElementById('btn');
btn.addEventListener('click', () => {
prefetch('/about');
});
</script>

The prefetch() API includes the same data saver mode and slow connection detection so that it only prefetches when needed.

To ignore slow connection detection, you can use the ignoreSlowConnection option:

// Prefetch even on data saver mode or slow connection
prefetch('/about', { ignoreSlowConnection: true });

Make sure to only import prefetch() in client-side scripts as it relies on browser APIs.

When you use View Transitions on a page, prefetching will also be enabled by default. It sets a default configuration of { prefetchAll: true } which enables prefetching for all links on the page.

You can customize the prefetch configuration in astro.config.mjs to override the default. For example:

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
// Disable prefetch completely
prefetch: false
});
astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
// Keep prefetch, but only prefetch for links with `data-astro-prefetch`
prefetch: {
prefetchAll: false
}
});

Astro’s prefetching uses <link rel="prefetch"> if supported by the browser, and falls back to the fetch() API otherwise.

The most common browsers support Astro’s prefetching with subtle differences:

Chrome supports <link rel="prefetch">. Prefetching works as intended.

Firefox supports <link rel="prefetch"> but may display errors or fail entirely:

  • Without an explicit cache header (e.g. Cache-Control or Expires), prefetching will error with NS_BINDING_ABORTED.
  • Even in the event of an error, if the response has a proper ETag header, it will be re-used on navigation.
  • Otherwise, if it errors with no other cache headers, the prefetch will not work.

Safari does not support <link rel="prefetch"> and will fall back to the fetch() API which requires cache headers (e.g. Cache-Control, Expires, and ETag) to be set. Otherwise, the prefetch will not work.

Edge case: ETag headers do not work in private windows.

To best support all browsers, make sure your pages have the proper cache headers.

For static or prerendered pages, the ETag header is often automatically set by the deployment platform and is expected to work out of the box.

For dynamic and server-side rendered pages, set the appropriate cache headers yourself based on the page content. Visit the MDN documentation on HTTP caching for more information.

Migrating from @astrojs/prefetch

Section titled Migrating from @astrojs/prefetch

The @astrojs/prefetch integration was deprecated in v3.5.0 and will eventually be removed entirely. Use the following instructions to migrate to Astro’s built-in prefetching which replaces this integration.

  1. Remove the @astrojs/prefetch integration and enable the prefetch config in astro.config.mjs:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import prefetch from '@astrojs/prefetch';
    export default defineConfig({
    integrations: [prefetch()],
    prefetch: true
    });
  2. Convert from @astrojs/prefetch’s configuration options:

    • The deprecated integration used the selector config option to specify which links should be prefetched upon entering the viewport.

      Add data-astro-prefetch="viewport" to these individual links instead.

      <a href="/about" data-astro-prefetch="viewport">
    • The deprecated integration used the intentSelector config option to specify which links should be prefetched when they were hovered over or focused.

      Add data-astro-prefetch or data-astro-prefetch="hover" to these individual links instead:

      <!-- You can omit the value if `defaultStrategy` is set to `hover` (default) -->
      <a href="/about" data-astro-prefetch>
      <!-- Otherwise, you can explicitly define the prefetch strategy -->
      <a href="/about" data-astro-prefetch="hover">
    • The throttles option from @astrojs/prefetch is no longer needed as the new prefetch feature will automatically schedule and prefetch optimally.

Contribute

What’s on your mind?

Create GitHub Issue

Quickest way to alert our team of a problem.

Community