Skip to main content
Easily create better & faster websites with the Total WordPress Theme Learn More
(opens a new tab)

Complete Guide to Speculative Loading in WordPress

complete-guide-to-speculative-loading-in-wordpress
Article by AJ Clarke(opens new tab) (staff)
Published on May 6, 2025 · 13 minute read
Loading blocks with a hand

WordPress 6.8 introduced a highly requested feature: Speculative Loading. But what exactly is it, and how does it affect your website? In simple terms, and in WordPress specifically, it’s a technique that makes your site feel faster by predicting which page(s) a visitor is likely to view next and preloading them.

In this guide, we’ll walk through everything you need to know about speculative loading, specifically as it relates to WordPress. By the end, you’ll be able to decide whether to keep it (it’s enabled by default) or disable it.

Table of contents

What is Speculative Loading

Speculative loading is a technique where the browser loads resources (like images, scripts, fonts, and even full pages) before the user actually requests them. These actions are based on predictions as to what pages the user is most likely to visit next or based on hints in the code. This can include DNS lookups, resource fetching, or even rendering documents in the background.

Predictions can be supplied by developers (like telling the browser which pages are the most popular) or determined by browser heuristics, such as patterns in the user’s browsing history. When it works well, speculative loading can make your pages load noticeably faster or even feel instant.

If you’re using Google Fonts, you might’ve seen code like this in your site’s <head> tag.

<link rel='dns-prefetch' href='//fonts.googleapis.com' />

This code, added by the wp_resource_hints() function in WordPress core, tells the browser to perform a DNS lookup in advance for the Google Fonts API. As a result, when the font is actually needed, it loads faster because the DNS step has already been completed.

Each time a page loads, WordPress checks the enqueued assets. If it detects assets from external domains (like Google Fonts), it adds the appropriate dns-prefetch or preconnect tags.

This is a simple example, but speculative loading goes much further. Beyond just hinting at which assets to prefetch, you can now tell the browser to prefetch or even prerender entire URLs. That’s exactly what was introduced in WordPress 6.8.

For those who want a deeper technical understanding, Mozilla’s documentation on speculative loading is an excellent resource.

Speculative Loading in WordPress

In the WordPress 6.8 release announcement, speculative loading was introduced as a new feature. However, it already existed through the Resource Hints API (like the example shared above). What’s new is that WordPress now includes actual speculative preloading powered by the Speculation Rules API.

To maintain consistency, from this point on, when I refer to speculative loading, I’m specifically referring to the new functionality introduced in WordPress 6.8. This feature uses the Speculation Rules API to preload full URLs based on what the browser predicts the user will visit next.

For example, if someone visits your homepage, WordPress might predict that they’ll click on the blog link next. While the visitor is still on the homepage, WordPress starts preloading the blog page in the background. So when the user clicks, the page appears almost instantly.

Speculation Rules API

According to the Speculation Rules API, it is a flexible syntax for defining what outgoing links can be prepared speculatively before navigation. So rather than the browser doing all the guess work, developers can add code to their website to explicitly say:

Hey browser, the user might click this link soon, so go ahead and start preparing that page in the background.

To make use of the Speculation Rules API, you simply need to add some JSON code to your site which defines the rules the browser should follow. The API itself exists in the browser, this isn’t something that needs to be added and loaded by your site.

Strategies

There are 2 main strategies that can be used with the Speculation Rules API:

1. Prefetch

  • Downloads the HTML of the target page.
  • The browser doesn’t render or execute the page, rather it’s stored for faster retrieval.
  • Ideal strategy for “medium confidence” predictions (the user might click something).

2. Prerender

  • Fully loads and renders the target page in the background.
  • The page is ready to display the moment the user clicks.
  • Best for “high confidence” predictions, but uses more memory.

Your website can create rules for both strategies. Currently, the default rules added by WordPress make use of the prefetch strategy.

Browser Support

As of as of 2025, the Speculation Rules API is supported in Chromium-based browsers, but not yet in Firefox or Safari. You can refer to the popular caniuse.com website to view the current browser support for speculation rules.

This means that, at the time of writing this post, your site visitors will need to use an up to date version of Chrome, Edge or Opera to take advantage of the feature. The code will still be available on your site for non-supported browsers, but because the Speculation Rules API is a progressive enhancement it won’t cause any errors on issues (it’s simply ignored by the browser).

Default Speculation Rules in WordPress

WordPress adds default speculation rules for logged-out users which look like this:

<script type="speculationrules">
{
  "prefetch": [
    {
      "source": "document",
      "where": {
        "and": [
          {
            "href_matches": "/*"
          },
          {
            "not": {
              "href_matches": [
                "/wp-*.php",
                "/wp-admin/*",
                "/wp-content/uploads/*",
                "/wp-content/*",
                "/wp-content/plugins/*",
                "/wp-content/themes/twentytwentyfive/*",
                "/*\\?(.+)"
              ]
            }
          },
          {
            "not": {
              "selector_matches": "a[rel~=\"nofollow\"]"
            }
          },
          {
            "not": {
              "selector_matches": ".no-prefetch, .no-prefetch a"
            }
          }
        ]
      },
      "eagerness": "conservative"
    }
  ]
}
</script>

Here is a breakdown of the code:

  • prefetch Tells the browser to download the HTML in advance but doesn’t render it.
  • source:"document" This tells the browser to scan the current document for <a> links and apply the rules to them.
  • href_matches: "/*" Prefetch any link that matches the root of the site (internal site links).
  • not: These are the exclusions (links to ignore).
    • Exclude admin and login pages.
    • Exclude plugins, uploads, themes: Skips media and static asset links.
    • Exclude links with query strings (e.g., /page?foo=bar).
    • Exclude links with re="nofollow" attributes.
    • Exclude links with the .no-prefetch class or child links of the class.
  • eagerness: "conservative": Tells the browser to be cautious and only prefetch when it’s “confident” the user might click (such as when hovering a link). Other options are moderate or eager which are more “aggressive”.

These rules tell the browser to take a cautious approach when prefetching internal page links, excluding admin, plugin, upload, and content directories, as well as links with query strings, links marked with rel=”nofollow”, and any links containing the .no-prefetch class.

How to Customize the WordPress Speculation Rules

Because WordPress doesn’t know how your visitors use your site, it applies generic rules (which will work for most sites). Fortunately, you can customize them using several hooks (to an extent).

  1. wp_speculation_rules_configuration (filter)
  2. wp_speculation_rules_href_exclude_paths (filter)
  3. wp_load_speculation_rules (action)

These hooks aren’t currently documented in the official Codex. I found them by exploring the WordPress GitHub repository. There may be other useful hooks available that I’m not aware of (or that could be added in the future), but these are likely all you’ll need to make your edits.

How to Modify the Speculation Rules Configuration

You can use the wp_speculation_rules_configuration filter to adjust the default configuration of speculation rules, including changing the mode and eagerness. This filter also lets you completely disable the default speculative rules.

Here’s an example snippet that uses this filter to modify the default configuration:

/**
 * Modify the default Speculation Rules configuration in WordPress.
 *
 * Changes the mode from 'prefetch' to 'prerender' and sets the eagerness to 'moderate'.
 *
 * @param array $config Existing configuration for speculative loading.
 * @return array Modified configuration.
 */
function my_custom_speculation_rules_config( $config ) {
	if ( is_array( $config ) ) {
		$config['mode']      = 'prerender'; // prerender or prefetch
		$config['eagerness'] = 'moderate'; // conservative, moderate, or eager
	}

	return $config;
}
add_filter( 'wp_speculation_rules_configuration', 'my_custom_speculation_rules_config' );

In this example, we add an is_array() check. This is important because the $config variable can sometimes be null (that’s how you disable the feature completely).

How to Exclude Specific URL’s from Speculative Loading

The wp_speculation_rules_href_exclude_paths filter lets you define a list of URL path patterns to exclude from speculative loading.

Here’s a sample snippet that shows how to exclude a custom post type from speculative loading. This assumes you’re using pretty permalinks where your post type URLs include /custom-post-type/ in the slug:

/**
 * Exclude specific URL paths from speculative loading in WordPress.
 *
 * @param string[] $exclude_paths Array of regex patterns for paths to exclude.
 * @return string[] Modified array of exclude path patterns.
 */
function my_excluded_speculation_paths( $exclude_paths ) {

    // Exclude custom paths (e.g., anything starting with /custom-post-type/)
    $exclude_paths[] = '/custom-post-type/.*';

    return $exclude_paths;
}
add_filter( 'wp_speculation_rules_href_exclude_paths', 'my_excluded_speculation_paths' );

I think the filter name could be clearer, as it implies you should be able to modify the current exclusions. However, it only allows you to add new ones, as the default value passed to the filter is an empty array.

How to Add New Speculation Rules

You can use the wp_load_speculation_rules action hook to modify the speculation rules when they’re loaded, using the WP_Speculation_Rules class. This action hook lets you add your own custom rules.

Here’s an example of how you might add a new rule:

/**
 * Add custom prerender rules for specific URLs using the Speculation Rules API.
 *
 * @param WP_Speculation_Rules $speculation_rules The rules object provided by WordPress.
 */
function my_add_custom_speculation_rules( $speculation_rules ) {
	if ( ! is_a( $speculation_rules, 'WP_Speculation_Rules' ) ) {
		return;
	}

	// Add a custom rule for our "special-offer" page
	$speculation_rules->add_rule(
		'prerender', // Rule type: either prerender or prefetch
		'custom-prerender-rule', // A unique key/ID for this rule
		[
			'source'          => 'list', // 'list' means we are explicitly listing URLs ur 'document' to scan the document for links
			'urls'            => [
				'/black-friday-sale/',
			],
			'eagerness'       => 'eager', // Mode: conservative, moderate, or eager

			// Optional metadata
			'priority'        => 1, // Priority of the rule (1-10) - lower number means higher priority
			'referrer_policy' => 'strict-origin-when-cross-origin', // Referrer policy for the request
			'options'         => [
				'allow-credentials' => true, // Whether to send cookies/auth with request
				'allow-redirects'   => true, // Whether to allow following redirects
			],
		],
	);
}
add_action( 'wp_load_speculation_rules', 'my_add_custom_speculation_rules' );

Let’s say you’re running a big Black Friday sale and expect many visitors to click on your sale banner. Adding a custom rule for this page with a higher priority and more aggressive eagerness would make sense. The example above achieves this.

How to Remove or Modify Default Exclusions

WordPress provides three helpful filters, as discussed above, to control the speculative loading rules on your site. However, the WP_Speculation_Rules class doesn’t provide methods to modify or remove existing rules (this may change in the future).

For example, if you want to allow speculative loading for items in the /wp-content/ folder, there’s currently no method to remove this path from the default “not” parameter.

If you need complete control over speculative loading rules, consider disabling WordPress’s built-in rules and insert your own JSON script.

How to Check if Speculative Loading is Working

To verify that speculative loading is working, inspect your site using your browser’s developer tools. I’ll explain how to do this in Chrome:

  1. Open Chrome and visit your website’s homepage.
  2. Ensure you are logged out (speculative loading is disabled for logged-in users).
  3. Right-click anywhere on the page and click “Inspect”.
  4. Once the developer tools panel opens click on “Application”.
  5. On the right side, under “Background Services,” you’ll see “Speculative Loads”.
Total theme speculative rules

If your site is correctly implementing speculative loading, you should see the rules under this section. Clicking on the “Speculations” tab will display all the URLs that can be prefetched, along with their current status.

In my experience, the status of a page doesn’t change just by hovering over links. However, clicking a link does seem to trigger the prefetching. After clicking a link for a page listed in the “Speculations” tab, then hitting the back button, the status will change.

WordPress takes a more conservative approach to speculative loading, so changing the configuration to set the eagerness to “eager” during testing can be helpful.

Issues & Concerns With Speculative Loading

WordPress enables speculative loading by default on all sites, but it doesn’t offer a simple way to disable it through the admin interface. The implication seems to be that if WordPress turned it on, you must need it… right?

Well, speculative loading has some drawbacks. I’ll explain them so you can decide whether to disable it on your site.

Unnecessary Server Usage

This is likely the biggest concern for most WordPress users. Your server may begin receiving requests for pages users never actually visit. On high-traffic sites, this can increase resource usage and affect performance and hosting costs. Since speculative loading relies on predictions, it might lead to requests for pages and resources that users never actually visit.

Potential for Serving Outdated Content

If your website is updated frequently, speculative loading could serve outdated content. For example, a real-time news site could experience issues when prefetching articles that update with new information. If a user clicks on a preloaded article, they may see the old version, not the updated one.

Browser Support

As I mentioned earlier, speculative loading doesn’t work in Safari or Firefox. While this isn’t a reason to disable it, it’s a drawback. If most of your users use these browsers, they won’t benefit from speculative loading.

Potential Plugin Conflicts

Some plugins rely on scripts that only run after a page load (e.g., session starts, cookie checks, or custom redirects). Speculative loading can conflict with these plugins. Since speculative loading is part of WordPress core, plugin developers should update their plugins to properly exclude speculative loading where necessary.

It may take time for plugin developers to adapt to new core features and release fixes. If a plugin causes issues, you may need to temporarily disable speculative loading until it is fully supported.

How to Disable Speculative Loading in WordPress

If you determine that speculative loading isn’t suitable for your site, you can easily disable it. While WordPress doesn’t provide a simple toggle option in the admin, you can disable it by adding the following code:

// Disable Speculative Loading Completely
add_filter( 'wp_speculation_rules_configuration', '__return_empty_array' );

Place this in your child theme’s functions.php file, or use a plugin like Code Snippets.

Conclusion

Speculative Loading in WordPress is designed to improve perceived performance by preloading pages before the user clicks them. In many cases, it’s a valuable enhancement. However, it does have trade-offs, especially for sites with high traffic, real-time content, or plugin compatibility issues.

My main concern is that WordPress enabled it by default without offering a simple admin toggle. Non-developers may not even know it’s active or how it affects their site.

Whether you choose to keep it enabled, customize the rules, or turn it off entirely, I hope you found this article helpful. If you did, feel free to share it!

You may be interested in the following related articles:

Disclaimer: WPExplorer may be an affiliate for one or more products listed in the article. If you click a link and complete a purchase we could make a commission.
Recent in WordPress Tips