Get the Newsletter

Handling Links

This article covers Aurelia's default behavior on handling links.

Basic Concept

When you use Aurelia router in your app, most links (in <a> elements) are processed by Aurelia without triggering a traditional full page reload. This is a fundamental feature of any SPA (Single Page Application) framework.

Aurelia achieves this with DefaultLinkHandler in aurelia-history-browser.

It basically registered a global click event handler to hijack click on <a> elements, then does front-end navigation instead of default browser behavior which is a full page reload.

Skipping Click Hijacking

By default, the DefaultLinkHandler skips click hijacking in following situations.

1. if it's not clicking primary button (left button for right-handed).

2. if any of Alt/Ctrl/Meta/Shift keys is pressed.

3. if the href on <a> element starts with # (link to local hash), or it's a full url like https://... or ftp://....

4. if the <a> has a target attribute and it is not targeting the current window.

    
  <a href="/some/link" target="_blank">Skip Hijacking</a>
  
  <a href="/some/link">Does Not Skip</a>
  <a href="/some/link" target="_self">Does Not Skip</a>
  <a href="/some/link" target="name-of-current-window">Does Not Skip</a>

5. if the <a> has special attribute download, or router-ignore, or data-router-ignore.

    
  <a href="/some/link" download>Skip Hijacking</a>
  <a href="/some/link" download="">Skip Hijacking</a>
  <a href="/some/link" router-ignore>Skip Hijacking</a>
  <a href="/some/link" router-ignore="">Skip Hijacking</a>
  <a href="/some/link" data-router-ignore>Skip Hijacking</a>
  <a href="/some/link" data-router-ignore="">Skip Hijacking</a>

Conditional Skipping Click Hijacking

The data-router-ignore is introduced to play nice with another Aurelia feature: automatic data attribute creation.

You might have already used this Aurelia feature without notice. This feature is why you can do <span data-placement.bind="tooHigh ? 'bottom' : 'top'" data-toggle="tooltip" title="lorem">test</span> with bootstrap.

    
  <a href="/some/link" data-router-ignore.bind="condition || null">Conditional Skip Hijacking</a>

Here Aurelia will dynamically add/remove attribute data-router-ignore when condition changes. Note || null is necessary because Aurelia only removes the data attribute when the bound value becomes null or undefined, it doesn't remove the data attribute when bound value is 0 or "" or even false.

In comparison, <a href="/some/link" router-ignore.bind="condition || null">Does not work</a> does NOT add/remove attribute router-ignore. Aurelia only does that for data- or aria- attributes.