<div style="text-align:center"></div><div>
<p>WordPress 6.8 introduces speculative loading, which can lead to near-instant page load times by loading URLs before the user navigates to them. The feature relies on the <a href="https://wicg.github.io/nav-speculation/speculation-rules.html">Speculation Rules API</a>, a web platform feature that allows defining rules for which kinds of URLs to prefetch or prerender, and how early such speculative loading should occur.</p>
<p>Please refer to the <a href="https://make.wordpress.org/core/2024/04/09/speculative-loading-in-wordpress/">speculative loading announcement post</a> for additional information about the Speculation Rules API and related prior art in WordPress Core.</p>
<h2 class="wp-block-heading">Context</h2>
<p>Prior to being implemented in WordPress Core, the feature has been successfully used on over 50,000 WordPress sites via the <a href="https://wordpress.org/plugins/speculation-rules/">Speculative Loading feature plugin</a>, which has been ported over to Core now, with a <a href="https://make.wordpress.org/core/2025/03/06/speculative-loading-in-6-8/#default-behavior-and-customization" data-type="internal" data-id="#default-behavior-and-customization">few modifications</a>. Based on data queried from the <a href="https://httparchive.org/">HTTP Archive</a> and <a href="https://developer.chrome.com/docs/crux">Chrome User Experience Report (CrUX)</a> datasets over all the time since the plugin launched, the sites that enabled speculative loading improved their Largest Contentful Paint (LCP) passing rate by ~1.9% at the median which, while it may seem a small number, is a huge boost for a single feature, considering that a lot of sites with various performance implications contribute to the data.</p>
<p>The Speculation Rules API was first introduced in early 2023 and has seen ever increasing usage since then. Today, <a href="https://chromestatus.com/metrics/feature/timeline/popularity/3932">over 8% of Chrome navigations rely on Speculation Rules</a>. A related significant launch happened a few months ago when <a href="https://blog.cloudflare.com/introducing-speed-brain/">Cloudflare enabled speculative loading at large scale via its Speed Brain feature</a>.</p>
<p>The Speculation Rules API is <a href="https://caniuse.com/mdn-html_elements_script_type_speculationrules">supported by Chrome, Edge, and Opera so far</a>, which means the vast majority of end users browsing the web can benefit from its capabilities. For users of browsers without support for the API, there are no adverse effects, since the Speculation Rules API is a progressive enhancement. Browsers without support simply ignore its presence, i.e. sites maintain the same behavior as before.</p>
<h2 class="wp-block-heading" id="default-behavior-and-customization">Default behavior and customization</h2>
<p>The WordPress Core implementation enables speculative loading by default in the frontend of all sites, except when a user is logged in or when a site has pretty permalinks disabled. URLs are prefetched with conservative eagerness: this means that prefetching is triggered when a user starts to click on a link. While this is typically only a fraction of a second before the actual navigation occurs, it is still enough to lead to a notable performance improvement.</p>
<p>This default of <code>prefetch</code> with <code>conservative</code> eagerness is used as a reasonable starting point to enable speculative loading at the scale of WordPress. It is in line with the configuration that Cloudflare uses in its speculative loading feature, and it minimizes the chance of any speculative loads without a subsequent navigation to the URL. The Speculative Loading plugin uses a default of <code>prerender</code> with <code>moderate</code> eagerness, which leads to a larger performance improvement due to the speculative load being triggered earlier as well as prerendering the URL, but also has tradeoffs related to certain client-side behavior inadvertently being triggered even in case the user never ends up navigating to the URL.</p>
<h3 class="wp-block-heading">Customization via actions and filters</h3>
<h4 class="wp-block-heading" id="excluding-url-patterns">Excluding URL patterns from speculative loading</h4>
<p>When a URL is prefetched, the server response is loaded before the user navigates to it. In most cases, this is not an issue since server responses for frontend URLs do not typically change the state of the site in any way. However, there may be plugins that use the pattern of so-called “action URLs”, where simply navigating to a specific URL (with a <code>GET</code> request) a state change occurs—for example on an e-commerce WordPress site, it could be adding a product to the shopping cart or marking an item as a favorite. It is worth noting that this is an antipattern, since state changes should typically be triggered only by <code>POST</code> requests, e.g. via form submissions, and <code>GET</code> requests are supposed to be “idempotent”. Despite that, plugins that use this pattern should ensure that such URLs are excluded from prefetching and prerendering. In the case of <code>conservative</code> eagerness, this should not be an issue since it’s almost guaranteed the user will also navigate to the URL. But for sites that use a more eager configuration there is a chance the navigation will never occur, which is why excluding such URLs is important.</p>
<p>By default, any URLs that include query parameters are excluded from prefetching and prerendering automatically, which should cater for the majority of such action URLs. However, in case a plugin is implementing its own rewrite rules for these URLs instead of using custom query parameters, they can use the <code>wp_speculation_rules_href_exclude_paths</code> filter to provide URL patterns to exclude.</p>
<p>This example ensures that any URLs with a path starting in “/cart/” will be excluded from speculative loading, regardless of whether it’s <code>prefetch</code> or <code>prerender</code>:</p>
<div class="wp-block-syntaxhighlighter-code ">
<pre class="brush: php; title: ; notranslate">
add_filter(
	'wp_speculation_rules_href_exclude_paths',
	function ( $href_exclude_paths ) {
		$href_exclude_paths[] = '/cart/*';
		return $href_exclude_paths;
	}
);
</pre>
</div>
<p>All URL patterns provided should follow the <a href="https://urlpattern.spec.whatwg.org/">URL Pattern web specification</a>, and they will all be considered relative to the frontend of the site. For sites where the home URL is in a subdirectory, WordPress will automatically prefix the corresponding path segment so that plugin developers do not need to worry about that.</p>
<p>While WordPress Core’s default behavior is to prefetch URLs, sites may opt in to prerendering URLs. This leads to a significant performance boost, but also has additional implications on the speculatively loaded URLs, since even their client-side code will be loaded. If a site contains any client-side logic that should only run once the user actually navigates to the URL, it needs to check for whether the site is being prerendered first and only trigger such logic once the navigation has occurred (see <a href="https://developer.chrome.com/docs/web-platform/prerender-pages#detect-prerender-in-javascript">“Detect prerender in JavaScript” documentation</a>). A common use-case for that is analytics tooling (see <a href="https://developer.chrome.com/docs/web-platform/prerender-pages#impact-on-analytics">“Impact on analytics” documentation</a>). Many popular providers already support prerendering, so no change is necessary. But if your site or your plugin includes such functionality on certain URLs and you haven’t updated the JavaScript logic to support prerendering yet, you can temporarily exclude the relevant URLs from prerendering specifically.</p>
<p>This example ensures that any URLs with a path starting in “/personalized-area/” will be excluded from <code>prerender</code> speculative loading only:</p>
<div class="wp-block-syntaxhighlighter-code ">
<pre class="brush: php; title: ; notranslate">
add_filter(
	'wp_speculation_rules_href_exclude_paths',
	function ( $href_exclude_paths, $mode ) {
		if ( 'prerender' === $mode ) {
			$href_exclude_paths[] = '/personalized-area/*';
		}
		return $href_exclude_paths;
	},
	10,
	2
);
</pre>
</div>
<h4 class="wp-block-heading">Modifying the default speculative loading configuration</h4>
<p>As mentioned before, WordPress sites are able to modify the default speculative loading configuration. For further improved performance, you may want the configuration to be more eager or to leverage prerendering. This can be achieved via the <code>wp_speculation_rules_configuration</code> filter, which receives either an associative array with <code>mode</code> and <code>eagerness</code> keys to control the configuration, or <code>null</code> to disable speculative loading for the current request.</p>
<p>The default value for the filter is <code>array( 'mode' => 'auto', 'eagerness' => 'auto' )</code>, unless a user is logged-in or the site has pretty permalinks disabled, in which case the default value is <code>null</code>. For both configuration parameters, the value auto signifies that WordPress Core will decide on the configuration, which as of today effectively leads to a <code>mode</code> of <code>prefetch</code> and an <code>eagerness</code> of <code>conservative</code>. Depending on various criteria such as the state of the Speculation Rules API and ecosystem support, the behavior may change in a future WordPress release.</p>
<p>Here is an example that uses the filter to increase the eagerness to <code>moderate</code>. This will improve the performance benefits, while increasing the tradeoff for a speculative load without subsequent navigation:</p>
<div class="wp-block-syntaxhighlighter-code ">
<pre class="brush: php; title: ; notranslate">
add_filter(
	'wp_speculation_rules_configuration',
	function ( $config ) {
		if ( is_array( $config ) ) {
			$config['eagerness'] = 'moderate';
		}
		return $config;
	}
);
</pre>
</div>
<p>The <code>mode</code> value can be either <code>auto</code>, <code>prefetch</code>, or <code>prerender</code>, and the <code>eagerness</code> value can be either <code>auto</code>, <code>conservative</code>, <code>moderate</code>, or <code>eager</code>. The Speculation Rules API also defines another eagerness value of <code>immediate</code>, however that value is strongly discouraged for document-level rules that speculatively load any URLs, so the WordPress Core API does not allow using it for its overall configuration.</p>
<p>If you wanted to opt for an even greater performance boost, here is an example that uses the filter to opt for <code>prerender</code> with <code>moderate</code> eagerness. This is similar to what the <a href="https://wordpress.org/plugins/speculation-rules/">Speculative Loading feature plugin</a> implements, and it can lead to a significant performance boost. Please keep in mind the effects of prerendering on client-side JavaScript logic explained in the previous section before enabling <code>prerender</code>.</p>
<div class="wp-block-syntaxhighlighter-code ">
<pre class="brush: php; title: ; notranslate">
add_filter(
	'wp_speculation_rules_configuration',
	function ( $config ) {
		if ( is_array( $config ) ) {
			$config['mode'] = 'prerender';
			$config['eagerness'] = 'moderate';
		}
		return $config;
	}
);
</pre>
</div>
<p>As mentioned before, speculative loading is disabled by default for sites that do not use pretty permalinks. This is because the aforementioned exclusion of URLs with query parameters would not reliably apply anymore if even WordPress Core’s arguments used query parameters. There may however be cases where, as a site owner of a site without pretty permalinks, you are confident that your site is not using any of the problematic patterns that are the reason for this exclusion in the first place, or you already identified them and explicitly excluded URLs with the specific query parameters from being speculatively loaded. In that case, you could use the filter to enable speculative loading, as seen here:</p>
<div class="wp-block-syntaxhighlighter-code ">
<pre class="brush: php; title: ; notranslate">
add_filter(
	'wp_speculation_rules_configuration',
	function ( $config ) {
		if ( ! $config && ! get_option( 'permalink_structure' ) ) {
			$config = array(
				'mode' => 'auto',
				'eagerness' => 'auto',
			);
		}
		return $config;
	}
);
</pre>
</div>
<p>Please use caution when opting into speculative loading like this. WordPress Core’s defaults were carefully considered to cater for the majority of sites in a safe way, so only use this code snippet if you are confident it will not have adverse effects on your site.</p>
<h4 class="wp-block-heading">Including additional speculation rules</h4>
<p>The Speculation Rules API allows defining multiple rules to configure how the browser should speculatively load URLs. By default, WordPress Core only includes a single rule that handles all the aforementioned behavior. More advanced customization is possible by providing entirely new speculation rules in addition to Core’s main rule, which can be accomplished by using the <code>wp_load_speculation_rules</code> action. The action receives an instance of the new <code>WP_Speculation_Rules</code> class, which has validation mechanisms built in and can be amended as needed. By adding new rules, you can implement entirely custom configurations that will be applied on top of WordPress Core’s main rule.</p>
<p>Here is an example, which directly relates to the previous example that changes the default configuration to <code>prerender</code> with <code>moderate</code> eagerness. You may prefer not to change the default, but there may be specific URLs where you would like to enable <code>prerender</code> with <code>moderate</code> eagerness. You could add a custom URL-level speculation rule for that:</p>
<div class="wp-block-syntaxhighlighter-code ">
<pre class="brush: php; title: ; notranslate">
add_action(
	'wp_load_speculation_rules',
	function ( WP_Speculation_Rules $speculation_rules ) {
		$speculation_rules->add_rule(
			'prerender',
			'my-moderate-prerender-url-rule',
			array(
				'source' => 'list',
				'urls' => array(
					'/some-url/',
					'/another-url/',
					'/yet-another-url/',
				),
				'eagerness' => 'moderate',
			)
		);
	}
);
</pre>
</div>
<p>Taking this example further, maybe there is no easy way to provide a list of URLs, e.g. in case they change often or more URLs need to be added regularly. In that case, you consider using a document-level speculation rule that applies for all links that are marked with a specific class, or where a parent element has a specific class:</p>
<div class="wp-block-syntaxhighlighter-code ">
<pre class="brush: php; title: ; notranslate">
add_action(
	'wp_load_speculation_rules',
	function ( WP_Speculation_Rules $speculation_rules ) {
		$speculation_rules->add_rule(
			'prerender',
			'my-moderate-prerender-optin-rule',
			array(
				'source' => 'document',
				'where' => array(
					'selector_matches' => '.moderate-prerender, .moderate-prerender a',
				),
				'eagerness' => 'moderate',
			)
		);
	}
);
</pre>
</div>
<p>With this rule in place, users would be able to add a <code>moderate-prerender</code> class to any block that supports the advanced UI for adding classes, and that way they could manually opt in any link on demand.</p>
<p>Please refer to the <a href="https://wicg.github.io/nav-speculation/speculation-rules.html">Speculation Rules API</a> specification for details on what a rule definition can look like.</p>
<h3 class="wp-block-heading">Customization via UI</h3>
<p>The previous example already hints at how speculative loading can be customized via the UI. While a dedicated UI for the feature like it exists in the <a href="https://wordpress.org/plugins/speculation-rules/">Speculative Loading feature plugin</a> is out of scope for WordPress Core, many block types provide an “Additional CSS class(es)” field in the “Advanced” panel in the block sidebar.</p>
<p>WordPress Core has built-in support for the CSS classes <code>no-prefetch</code> and <code>no-prerender</code>. You can add these to any block so that links within that block are opted out of prefetching or prerendering respectively. Note that <code>no-prefetch</code> opts out of both, i.e. opts out of speculative loading entirely, since prefetching is part of prerendering. Please refer to the <a href="https://make.wordpress.org/core/2025/03/06/speculative-loading-in-6-8/#excluding-url-patterns" data-type="internal" data-id="#excluding-url-patterns">section about excluding URL patterns</a> for guidance on when it may be useful to exclude URLs from prefetching or prerendering.</p>
<p>This mechanism makes it easy for advanced users to take granular control over speculative loading for specific blocks.</p>
<h2 class="wp-block-heading">Summary and further reading</h2>
<p>The speculative loading feature in WordPress 6.8 is a great win for performance of WordPress and the web overall, by starting the page load process even before the user navigation occurs. By fine-tuning it further based on your site’s needs, you can achieve even greater performance boosts than with the default configuration.</p>
<p>Please see the following links for further reading:</p>
<ul class="wp-block-list">
<li>Trac ticket <a href="https://core.trac.wordpress.org/ticket/62503">#62503</a> and changeset <a href="https://core.trac.wordpress.org/changeset/59837">[59837]</a> for additional context and discussion about the Core implementation.</li>
<li><a href="https://make.wordpress.org/core/2024/04/09/speculative-loading-in-wordpress/">Speculative loading announcement post</a> for Core</li>
<li><a href="https://developer.chrome.com/docs/web-platform/prerender-pages">Chrome developer article on using the Speculation Rules API</a></li>
<li><a href="https://developer.chrome.com/docs/devtools/application/debugging-speculation-rules">Chrome developer article on debugging Speculation Rules</a></li>
</ul>
<p class="has-text-align-right"><em>Props to <a href="https://profiles.wordpress.org/westonruter/" class="mention"><span class="mentions-prefix">@</span>westonruter</a>, <a href="https://profiles.wordpress.org/tunetheweb/" class="mention"><span class="mentions-prefix">@</span>tunetheweb</a>, <a href="https://profiles.wordpress.org/adamsilverstein/" class="mention"><span class="mentions-prefix">@</span>adamsilverstein</a>, <a href="https://profiles.wordpress.org/joemcgill/" class="mention"><span class="mentions-prefix">@</span>joemcgill</a> for review and proofreading.</em></p>
<p class="o2-appended-tags"><a href="https://make.wordpress.org/core/tag/6-8/" class="tag"><span class="tag-prefix">#</span>6-8</a>, <a href="https://make.wordpress.org/core/tag/dev-notes/" class="tag"><span class="tag-prefix">#</span>dev-notes</a>, <a href="https://make.wordpress.org/core/tag/dev-notes-6-8/" class="tag"><span class="tag-prefix">#</span>dev-notes-6-8</a>, <a href="https://make.wordpress.org/core/tag/feature-projects/" class="tag"><span class="tag-prefix">#</span>feature-projects</a>, <a href="https://make.wordpress.org/core/tag/performance/" class="tag"><span class="tag-prefix">#</span>performance</a></p>
</div>

Cloudways is bringing back its free Prepathon online event next week, from September 30 to…
Fueled has confirmed layoffs this week, cutting 4–5% of its workforce. But the news reached…
After calling for “more weirdness” in WordPress theme design earlier this year, Nick Hamze has…
FAIR has reached its first major milestone with the release of version 1.0 this week,…
The full chat log is available beginning here on Slack. WordPress Performance Trac tickets @westonruter…
Back in 2011, Jon Penland was selling centrifugal pumping units into the water and wastewater…