AnchorJS - Add deep anchor links to your docs

Overview

Examples of deep anchor links from across the web.

AnchorJS lets you drop deep anchor links (like these) onto any webpage, and be on your way.

You don't need to set up IDs or worry about urls. AnchorJS will respect your IDs if you have them, and generate them if you don't.

It uses an attractive link icon by default, but you can customize the display via options and CSS syling. The examples demonstrate a few customization ideas.

Finally, AnchorJS is lightweight, accessible, and has no dependencies.

Installation

Download AnchorJS using npm,

npm install anchor-js

or bower:

bower install anchor-js

(or just download it from github).

Then include the anchor.js file (or anchor.min.js) in your webpage.

<script src="anchor.js"></script>

You could also include it via a CDN like CDNJS or jsDelivr.

If you're using it from Node/CommonJS, include it via:

var anchorJS = require('anchor-js');
var anchors = new anchorJS();

Basic usage

AnchorJS provides the anchors.add() method which takes a CSS selector (similar to jQuery) for targeting elements you want to deep-link. Here are some usage examples.

/**
 * Example 1
 * Add anchors to all h1's on the page
 */
anchors.add('h1');

/**
 * Example 2
 * Adds anchors to elements that have been assigned the class '.anchored'
 */
anchors.add('.anchored');

/**
 * Example 3
 * If no selector is provided, it falls back to a default selector of:
 * 'h2, h3, h4, h5, h6'
 */
anchors.add();

Don't run it too late!

You need to add anchors to the page early in the page load process if you want browsers to jump to the ID properly.

We recommend you call anchors.add() before the DOM finishes loading...

<!-- Add anchors before the closing body tag. -->
  <script>
    anchors.add();
  </script>
</body>

...or on DOMContentLoaded:

// Add anchors on DOMContentLoaded
document.addEventListener("DOMContentLoaded", function(event) {
  anchors.add();
});

Don't add anchors on later events, like $(document).ready() or window.onload as some browsers will attempt to jump to your ID before AnchorJS can add it to the page. For more details, see github issue #69).

Options

You can set a number of options to customize how your anchors look:

Option	Accepted Values	Default Value	Description
`placement`	`right` `left`	`right`	`right` appends the anchor to the end of the element. `left` places it to the left, in the margin.
`visible`	`hover` `always` `touch`	`hover`	`hover` displays the anchor when hovering over the element. `always` will always display the anchor link. `touch` will always display anchors for devices that support touch events, and only display them via hover for devices that do not support touch events. This approximates touchscreen detection (but isn't 100% accurate).
`icon`	(any unicode character)	``	Replace the default link icon with the character(s) provided. These are a few good options: `#`, `¶`, `❡`, and `§`.
`class`	(any string)	(none)	Adds the provided class(es) to the anchor html.
`truncate`	(any positive number)	`64`	Truncates the generated ID to the specified character length. Note: the length may not be exactly the same, if there are dangling spaces or hyphens to be trimmed.

For example:

/**
 * Example 1
 * Add anchors to all h1s, h2s and h3s inside of #post.
 * Anchors will be always visible.
 */
anchors.options.visible = 'always';
anchors.add('#post h1, #post h2, #post h3');

/**
 * Example 2
 * Provide options as an object before adding anchors to the page.
 * Adds always-visible ¶ anchors in the left margin of each p tag inside .story
 */
anchors.options = {
  placement: 'left',
  visible: 'always',
  icon: '¶'
};
anchors.add('.story > p');

Advanced usage

Section IDs

In some cases, you might want to link to existing section IDs instead of the heading element itself. You can instruct AnchorJS to do this with the data-anchor-id attribute:

<section id="section-1">
  <h3 data-anchor-id="section-1">Section 1</h3>
  <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed...</p>
</section>

This allows you to do things like highlight sections when your users jump to them.

Removing anchors

You can remove anchors with the anchors.remove() or anchors.removeAll() methods:

/**
 * Example 1
 * Remove anchors from all h1s on the page.
 */
anchors.remove('h1');

/**
 * Example 2
 * Remove all anchors from the page.
 */
anchors.removeAll();

Removing anchors with .remove() should be uncommon. If you simply want anchors on a more selective group, consider using the CSS :not() pseudo-class when you add them, like so:

/**
 * Example 2
 * Add anchors to all h2s, except for those with a class of "no-anchor".
 */
anchors.add('h2:not(.no-anchor)');

Chaining commands

You can chain commands of add() and remove() (since they return a copy of anchors), but it's usually more performant to lean on CSS when targeting elements:

/**
  * Example 1
  * Adds anchors to `.my-anchors` and `.my-other-anchors` except for those
  * with a class of `no-anchor`.
  */
 anchors.add('.my-anchors').add('.my-other-anchors').remove('.no-anchor');

 /**
  * Example 2
  * A more performant way to add anchors to the same classes in Example 1 above.
  */
  anchors.add('.my-anchors:not(.no-anchor), .my-other-anchors:not(.no-anchor)');

Multiple sets of anchors

You can have multiple sets of anchors on one page, each with their own design. To do so, just create your own instances of the AnchorJS object:

var sidebarAnchors = new AnchorJS();
anchors.add('.main h2'); // The default instance.
sidebarAnchors.add('.sidebar h2'); // The new instance.

You can preset your instance with whatever options you like:

var sidebarAnchors = new AnchorJS({
  placement: 'left',
  icon: '¶'
});
sidebarAnchors.add('.sidebar h2');

Generating navigations

AnchorJS doesn't include methods for dynamically generating navigations (like a table of contents or jump nav). This is to keep AnchorJS lightweight and simple for the most common usecases.

However, AnchorJS does expose a list of all anchored elements at anchors.elements. This way, external code can look up the elements and use them to generate navigations (as shown in this example).

You can also use AnchorJS alongside a static navigation with pre-defined IDs (as is done in this example).