Which Links AjaxPress Handles
Most internal links load instantly under AjaxPress. Some deliberately do not. This page covers what is handled automatically, how to override it, and what to check when a link behaves unexpectedly.
Handled automatically
No configuration needed for any of these.
| Link type | Behaviour |
|---|---|
| External domain | Full page load |
target="_blank" | Opens in a new tab |
mailto: / tel: | Handed to the OS |
| File downloads (PDF, ZIP…) | Downloads normally |
| wp-admin links | Full page load — the dashboard is never part of the SPA |
Anchors (#section) | Scrolls, no navigation |
Links that act as buttons
Many themes build interactive controls from <a> tags: WooCommerce mini cart icons, offcanvas menu toggles, mega menu triggers, search overlays, quick-view buttons. They carry an href but are meant to open a panel, not navigate.
Failure signature: the panel opens, then the page navigates away anyway. On mobile this dropped shoppers on the cart page.
Handled as of 2.4.2, including themes that open panels from a shared click handler rather than one bound to the link. If you are on an earlier version, update first.
Excluding URLs
Settings → AjaxPress → Advanced → Exclude Links, one pattern per line:
/checkout
/my-account
/downloads/Any link matching a pattern gets a normal page load.
Exclusion trade-off
An excluded page is a page AjaxPress is not running on — so ajaxpress:ready does not fire there. Persistent players and any script that initialises on that event will not start on excluded pages.
Avoid excluding pages that contain a player. This limitation is known and on the fix list.
Exclude Links also operates on whole URLs, not individual elements. There is currently no per-element or per-form opt-out.
Diagnosing a link that reloads unexpectedly
- Is it truly internal?
https://www.example.comandhttps://example.comare different hostnames. - Does it match an exclusion? Check for a pattern broader than intended.
- Does the link set
target? Some builders add it silently. - Is another script calling
preventDefault()first? Common with mega menus. - Is it a JS-driven link?
<a href="#">with a click handler was never a navigation.
Detecting navigation in your own code
document.addEventListener('ajaxpress:ready', (e) => {
console.log(e.detail.url, e.detail.title);
});Fires once per navigation with the new URL and title.