Why Some Links Don’t Load Instantly — and How to Control Which Ones Do

Uncategorized • • 4 min read

EDITOR NOTE — remove before publishing. Accurate as of 2.4.2. The mini cart and _blank fixes landed in 2.4.1–2.4.2; re-check after the next release.

Once AjaxPress is running, most links on your site load instantly with no page refresh. But not all of them — and that’s on purpose.

Some links shouldn’t be handled by ajax. A PDF download, a link to another website, a payment gateway — those need a real page load. AjaxPress tries to work this out for you, and it mostly gets it right. This guide covers what it does automatically, and how to override it when it doesn’t.

What AjaxPress handles automatically

These are already left alone. You don’t need to configure anything.

Link typeWhat happens
External links (another domain)Normal page load
target="_blank"Opens in a new tab, as expected
mailto: and tel:Handed to the OS
File downloads (PDF, ZIP, etc.)Downloads normally
Links into wp-adminFull page load — the dashboard is never part of the SPA
Anchor links (#section)Scrolls, no navigation

A note on target="_blank": in older versions these were incorrectly opened in the same tab. If you’re seeing that, update — it was fixed. If you’re on the latest version and still seeing it, please tell us, because that’s a bug we thought was closed.

Links that act like buttons

This is the tricky category, and it’s where most of the confusion lives.

Plenty of themes build interactive controls out of <a> tags — a WooCommerce mini cart icon, an offcanvas menu toggle, a mega menu trigger, a search overlay, a quick-view button. They look like links and have an href, but clicking them is supposed to open a panel, not navigate anywhere.

The failure mode is distinctive: the panel opens and then the page navigates away anyway. On mobile, tapping the cart icon would open the mini cart and dump the shopper on the cart page.

This is handled as of 2.4.2, including themes that open panels from a shared click handler rather than one bound to the link itself. If you’re on an older version, update first — it’s very likely your issue.

Excluding a link yourself

When you need a specific link to do a full page load, go to Settings → AjaxPress → Advanced → Exclude Links and add a URL pattern:

/checkout
/my-account
/downloads/

Any link whose URL matches one of these gets a normal page load.

The exclusion trade-off you should know about

Worth stating plainly, because it has caught people out.

Excluding a page means AjaxPress isn’t running on it — and the ajaxpress:ready event doesn’t fire there. If you have a persistent audio player, or any script that initialises on that event, it won’t start on excluded pages.

So you can end up choosing between two things you want. We know, we don’t like it either, and it’s on the list to fix. In the meantime: avoid excluding pages that contain a player.

Exclude Links is also a blunt instrument — it works on whole URLs, not individual elements. If you need one specific form or button excluded on an otherwise-normal page, get in touch and tell us the case. We’re working on finer-grained opt-outs and real examples shape what we build.

When a link doesn’t trigger ajax at all

The opposite problem — a link that reloads the whole page when you expected it to be instant. Check these in order:

  1. Is it actually internal? A link to https://www.yoursite.com/page from https://yoursite.com/page counts as external — different hostname.
  2. Does it match an exclusion? Check your Exclude Links list for a pattern that’s broader than you meant.
  3. Does the link have target set? Some builders add target="_self" or _blank without you noticing.
  4. Is another script calling preventDefault() first? Common with mega menus and custom navigation scripts.
  5. Is it a JavaScript-driven link? An <a href="#"> with a click handler was never a navigation to begin with.

Knowing when navigation finished

Because pages load without a refresh, scripts that normally run on page load need a nudge. AjaxPress fires an event after every navigation:

document.addEventListener('ajaxpress:ready', (e) => {
  console.log('Now on', e.detail.url, '—', e.detail.title);
  // re-initialise sliders, lightboxes, counters here
});

It fires once per navigation with the new URL and title. If you’re dealing with analytics or a consent banner specifically, that has its own quirks — we’ve covered those separately.

Still not behaving?

Email [email protected] with the link’s HTML (right-click → Inspect → Copy → Copy outerHTML), a URL where we can see it, and what you expected to happen. That’s usually enough to answer the same day.

Related Posts