Lesson: Using Speculative Loading in WordPress

[thatmitchcanter]

Details

• Topic description: This lesson teaches the user about the Speculative Loading feature introduced in WordPress 6.8. It leverages the Speculation Rules API to enhance site performance by anticipating user navigation, and preloading or pre-rendering resources accordingly.
• Audience (User, Developer, Designer, Contributor, etc.): Developer
• Learning objectives (What will the learner be able to do as a result of this content?): The user will:
• • Understand the Speculative Loading feature and how it relates to the Speculative API
• • Understand how Speculative Loading enhances the user experience and performance
• • Understand how to use and tune the Speculative API beyond basic usage and integration
• Content type (Online Workshop, Lesson, Course, or Facilitator Notes): Lesson
• WordPress version (optional):
• Will you be creating this content? (Yes or No): Yes

Related Resources

• https://make.wordpress.org/core/2025/03/06/speculative-loading-in-6-8/
• https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API

Next steps for SMEs

Please follow the team handbook "Vetting topic ideas" to vet this topic.

[thatmitchcanter]

Introduction

This lesson is all about the Speculative Loading feature introduced in WordPress 6.8. Utilizing the Speculative Rules API, this feature allows a developer to prerender or preload content based on a user's predicted browsing path.

What is Speculative Loading?

Speculative Loading is the act of anticipating a user's navigation and preloading or prerendering resources. This, in turn, will allow for better website performance and a better user experience.

This feature was introduced in WordPress 6.8, and is powered by the Speculation Rules API - which is currently supported by Chrome, Edge, and Opera.

This feature is turned on by default as of WordPress 6.8, provided you are using a pretty permalink structure.

Tuning the Speculative Loading

There are several actions and filters available to fine tune the Speculation Rules for your WordPress site.

add_filter(
    'wp_speculation_rules_configuration',
    function ( $config ) {
        if ( is_array( $config ) ) {
            $config['mode']      = 'prerender';
            $config['eagerness'] = 'moderate';
        }
        return $config;
    }
);

The two most common values that can be set are mode and eagerness. The mode value sets what type of behavior is applied to the link (auto, prefetch, or prerender). The eagerness sets how aggressively the content is preloaded (auto, conservative, moderate, or eager).

Further Customizations

A good rule of thumb is to treat Speculative Loading like caching. Some pages, like eCommerce carts, should not be cached; those pages should also be excluded from Speculative Loading.

add_filter(
    'wp_speculation_rules_href_exclude_paths',
    function ( $href_exclude_paths ) {
        $href_exclude_paths[] = '/cart/*';
        return $href_exclude_paths;
    }
);

Applying a filter will allow you to have fine-tuned control over which pages you want to include - and exclude - from the Speculative Loading feature.

You can also add an action that will allow you to change the default configuration completely:

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

This code allows you to specify the array of URLs you want to change, and then set their eagerness (in this case, to moderate) to allow the exact behavior you want.

If you have a large amount of URLs, it may be easier to apply these rules with a selector - such as a class:

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

In this example, any link with a class of moderate-prerender (or any div with a child link) will use the moderate eagerness to preload resources.

_Note: WordPress Core has a class for .no-prefetch and .no-prerender built in - and those can be added to any block to opt out of prefetching and prerendering respectively.

For more information on the Speculative Loading API, and further examples, see this article by Feliz Arntz on Speculative Loading in 6.8