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.

Enable prefetching

Section titled Enable prefetching

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.

Prefetch configuration

Section titled Prefetch configuration

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

Prefetch strategies

Section titled Prefetch strategies

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

Default prefetch strategy

Section titled Default prefetch strategy

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'
  }
});

Prefetch all links by default

Section titled Prefetch all links by default

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.

Prefetch programmatically

Section titled Prefetch programmatically

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

Using with View Transitions

Section titled Using with View Transitions

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
  }
});

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.