A Field Guide to Speculative Loading in WordPress

Here’s a fun one: your WordPress site might already be reading your mind a little. Not in a creepy way – well, maybe a little in a creepy way – but in a “hey, I bet you’re about to click that” kind of way. If you’re running WordPress 6.8 or later, there’s a decent chance it’s already turned on.

The feature is called Speculative Loading – and it’s fairly easy to set up and tune, even if it’s already running on your site.

So what is Speculative Loading, exactly?

The short version: it’s WordPress anticipating where you’re about to navigate, and preloading – or in some cases fully pre-rendering – that page before you click. Guess right, and the next page just… appears. No spinner, no flash, no delay.

This isn’t a WordPress invention. It’s powered by the browser’s own Speculation Rules API, currently supported in Chrome, Edge, and Opera. WordPress Core wired it up starting in version 6.8. It’s turned on by default, provided you’re using a pretty permalink structure (which, if you’ve been building WordPress sites for more than about ten minutes, you almost certainly are). So: no plugin, no setup wizard, no toggle you had to find. It’s just… on.

Okay, but how does it actually decide?

“On by default” doesn’t mean “one-size-fits-all.” Just because it’s running doesn’t mean you don’t need to tune it a bit. There are two knobs you can dial in:

• mode: what actually happens to the link: auto, prefetch, or prerender. Prefetch grabs the resource. Prerender goes further and renders the whole page in the background, invisible, ready to swap in the instant you click.
• eagerness: how trigger-happy the guessing is: auto, conservative, moderate, or eager. The more eager it is, the more it preloads on a hunch instead of waiting for a stronger signal (like a hover).

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

Further Customizations

A good rule of thumb is to treat Speculative Loading like caching. Anything you wouldn’t want cached – a shopping cart, a checkout page, anything with session-specific or “must be fresh” content – you also don’t want speculatively loaded. Prerendering a cart page a visitor never actually opens is, at best, wasted server load. At worst, it’s a stale cart flashing the wrong contents for a split second, or worse: the wrong account information.

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

Going further: writing your own rules from scratch

If the built-in filters don’t give you enough control, there’s an action that lets you throw out the defaults entirely and hand-write your own rules – targeting a specific list of URLs:

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

And if you’ve got more URLs than you want to hand-list, you can opt pages in by CSS selector instead:

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

Now any link with a moderate-prerender class – or any container with a matching child link – gets the moderate-eagerness treatment.