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

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

```js
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();
```

## 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

##### root

Type: `HtmlElement`. Default: `document.documentElement`.

Links will be hijacked within this element.

##### skipModifierKeys

Type: `boolean`. Default: `true`.

By default, clicks paired with modifiers keys (`ctrlKey`, `altKey`, `metaKey`, `shiftKey`) are *not* hijacked.
If this option is `false`, these clicks *will* be hijacked.

##### skipDownload

Type: `boolean`. Default: `true`.

By default, links with the `download` attribute are *not* hijacked.
If this option is `false`, these links *will* be hijacked.

##### skipTargetBlank

Type: `boolean`. Default: `true`.

By default, links with the attribute `target="_blank"` are *not* hijacked.
If this option is `false`, these links *will* be hijacked.

##### skipExternal

Type: `boolean`. Default: `true`.

By default, links with the attribute `rel="external"` are *not* hijacked.
If this option is `false`, these links *will* be hijacked.

##### skipMailTo

Type: `boolean`. Default: `true`.

By default, links whose `href` attributes start with `mailto:` are *not* hijacked.
If this option is `false`, these links *will* be hijacked.

##### skipOtherOrigin

Type: `boolean`. Default: `true`.

By default, links pointing to other origins (protocol + domain) are *not* hijacked.
If this option is `false`, these links *will* be hijacked.

##### skipFragment

Type: `boolean`. Default: `true`.

By default, links with `href` attributes starting with fragments (e.g. `href="#foo"`) are *not* hijacked.
(Links with `href` attributes that *include* fragments, but don't start with them, will still be hijacked, e.g. `href="some/page#foo"`.)
If this option is `false`, these links *will* be hijacked.

##### skipFilter

Type: `Function`.

A filter function that receives the clicked link element and returns a truthy or falsey value indicating whether the link should be hijacked or not.
If it returns a falsey value, the link will be hijacked.
If the function returns a truthy value, the link will not be hijacked.

##### preventDefault

Type: `boolean`. Default: `true`.

By default, `event.preventDefault()` will be called on any click events that are hijacked (are *not* skipped).
If this option is `false`, `event.preventDefault()` will *not* be called.
You could let the event continue as normal, or prevent default behavior yourself.

#### callback

Type: `Function`.
**Required.**

Whenever a link is clicked, the `callback` will be invoked with two arguments:

- `link`: The link element that was clicked on or within.
- `event`: The `click` event.

## Similar work

- [page.js](https://github.com/visionmedia/page.js/blob/1034c8cbed600ea7da378a73716c885227c03270/index.js#L541-L601)
- [nanohref]( https://github.com/yoshuawuyts/nanohref/blob/4efcc2c0becd2822a31c912364997cf03c66ab8d/index.js)
- [whir-tools/hijack-links](https://github.com/whir-tools/hijack-links)