@mapbox/link-hijacker

v1.1.0

Published

2 years ago

Hijack clicks on and within links, probably for client-side routing

Downloads

1,268

@mapbox/link-hijacker

Hijack clicks on and within links, probably for client-side routing.

Imagine you're using client-side routing on your website, because you live in The Future. You want nice, smooth, fast client-side routing whenever a link points to a client-side route (regardless of whether the code author remembered this). And you want a regular old page transition whenever a link does not point to a client-side route. The easiest way to do this would be to use regular <a> elements all over your site, for both of these types of links. That would be convenient, and also wouldn't force you or others to pay attention to which links should do client-side routing and which ones should not. That seems like a better situation than, for example, using a special component to distinguish between regular and client-side links.

link-hijacker provides the means to do this by hijacking all clicks on and within links, allowing you to determine how they are treated.

Listens for clicks.
Determines which clicks are on or within <a> elements with href attributes.
Determines whether those links should be hijacked, based on your options.
If a link should be hijacked, prevents default behavior and calls your callback.
In your callback, you might programmatically change pages.

This pattern has been implemented before, because it's clearly useful (see "Similar work"). But there didn't seem to be a full-featured, well-tested, and actively maintained implementation that was not tied to a larger library. So we made this one.

Typical example

const linkHijacker = require('@mapbox/link-hijacker');

const unhijack = linkHijacker.hijack((clickedLink, clickEvent) => {
  // Determine whether the link points to a client-side route ...
  if (linkPointsToClientSideRoute) {
    // Use JS for to programmatically change the page ...
  } else {
    // Or else allow it to work like a regular link.
    window.location.assign(clickedLink);
  }
});

// Later, you can unhijack links.
unhijack();

You can now use <a> elements indiscriminately.

API

hijack

linkHijacker.hijack([options], callback)

Returns a function that can be used to remove event listeners, unhijacking links. Calls the callback whenever a link is hijacked.

options