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:

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 3 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.

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.
• Links that use the viewport strategy are prefetched with a lower priority to avoid clogging up the network.

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.js file:

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:

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>

You can additionally configure the priority of prefetching by passing the with option:

// Prefetch with `fetch()`, which has a higher priority.
prefetch('/about', { with: 'fetch' });

// Prefetch with `<link rel="prefetch">`, which has a lower priority
// and manually scheduled by the browser. (default)
prefetch('/about', { with: 'link' });

The prefetch() API includes the same data saver mode and slow connection detection, with fallback to the tap method.

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.js to override the default. For example:

import { defineConfig } from 'astro/config';

export default defineConfig({
  // Disable prefetch completely
  prefetch: false
})

import { defineConfig } from 'astro/config';

export default defineConfig({
  // Keep prefetch, but only prefetch for links with `data-astro-prefetch`
  prefetch: {
    prefetchAll: false
  }
})

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.js:

   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.