# AnchorJS - Add deep anchor links to your docs

## Overview

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.
`ariaLabel` | (any text) | `Anchor` | Allows you to customize or translate the default aria-label ("Anchor"), for screenreaders that encounter the link.

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>

    <!-- ... -->

    <script>
      anchors.add('h3');
    </script>

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).

## Examples

### Basic Link

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.options.visible = 'always';
    anchors.add('h3');

### Basic Link - Left

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.options = {
      visible: 'always',
      placement: 'left'
    };
    anchors.add('h3');

### Paragraph Link

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.options = {
      visible: 'always',
      placement: 'left',
      icon: '¶'
    };
    anchors.add('p');

### Octothorp

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.options = {
      visible: 'always',
      icon: '#'
    };
    anchors.add('h3');

### Unicode Icon 1

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.options = {
      visible: 'always',
      placement: 'left',
      icon: '§'
    };
    anchors.add('h3');

### Unicode Icon 2

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.options = {
      visible: 'always',
      icon: '❡'
    };
    anchors.add('p');

### Custom Text

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.options = {
      visible: 'always',
      icon: '# LINK'
    };
    anchors.add('h3');

    .anchorjs-link {
      font-weight: 200;
      margin-left: 1em;
      padding-right: 0.375em;
      font-size: 0.5em;
      border: 1px dashed #FFBAAC;
      vertical-align: middle;
    }

### Custom Image

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    // Use an empty string ('') for the icon when styling the background with CSS.
    anchors.options = {
      visible: 'always',
      placement: 'left',
      icon: ''
    };
    anchors.add('h3');

    .anchorjs-link {
      width: 14px;
      height: 32px;
      margin-top: 6px;
      margin-left: -1.25em !important;
      background: url('img/mini-logo.png') no-repeat;
    }

### Link w/CSS Styling

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.options = {
      visible: 'always',
      placement: 'left'
    };
    anchors.add('h3');

    .anchorjs-link {
      display: inline-block;
      height: 32px;
      width: 18px;
      border-radius: 50%;
      background-color: #FF5231;
      color: white;
      margin-top: 4px;
      margin-left: -1.4em !important;
    }
    .anchorjs-link:before {
      margin-left: 7px;
      margin-top: -4px;
      display: block;
    }

### Icon Font

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    // Just pass in the octal code for your icon-font character.
    anchors.options = {
      visible: 'always',
      icon: '\uf0c1'
    };
    anchors.add('h3');

    .anchorjs-link {
      font-family: 'your-icon-font';
    }

### SVG Icon

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.options = {
      visible: 'always',
      icon: ''
    };
    anchors.add('h3');

    .anchorjs-link {
      display: inline-block;
      background: url('img/hyperlink.svg') no-repeat;
      margin-left: 8px;
      width: 14px;
      height: 24px;
    }

### Base64 Icon

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.options = {
      visible: 'always',
      placement: 'left',
      icon: ''
    };
    anchors.add('h3');

    .anchorjs-link {
      background: url("data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+Cjxzdmcgd2lkdGg9IjIwcHgiIGhlaWdodD0iMTBweCIgdmlld0JveD0iMCAwIDIwIDEwIiB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiPgogICAgPGRlZnM+PC9kZWZzPgogICAgPGcgaWQ9IlBhZ2UtMSIgc3Ryb2tlPSJub25lIiBzdHJva2Utd2lkdGg9IjEiIGZpbGw9Im5vbmUiIGZpbGwtcnVsZT0iZXZlbm9kZCI+CiAgICAgICAgPGcgaWQ9ImxpbmsiIGZpbGw9IiNGRjUyMzEiPgogICAgICAgICAgICA8cGF0aCBkPSJNMTUsMCBMMTIuMzA0Njg3NSwwIEMxMy4yNDIxODc1LDAuNjI1IDE0LjEyMTA5MzgsMS43MzgyODEyNSAxNC4zOTQ1MzEyLDIuNSBMMTQuOTgwNDY4OCwyLjUgQzE2LjI1LDIuNSAxNy40ODA0Njg4LDMuNzUgMTcuNDgwNDY4OCw1IEMxNy40ODA0Njg4LDYuMjUgMTYuMjEwOTM3NSw3LjUgMTQuOTgwNDY4OCw3LjUgTDExLjIzMDQ2ODgsNy41IEMxMCw3LjUgOC43MzA0Njg3NSw2LjI1IDguNzMwNDY4NzUsNSBDOC43MzA0Njg3NSw0LjU1MDc4MTI1IDguODY3MTg3NSw0LjEyMTA5Mzc1IDkuMDgyMDMxMjUsMy43NSBMNi40MDYyNSwzLjc1IEM2LjMwODU5Mzc1LDQuMTYwMTU2MjUgNi4yNSw0LjU3MDMxMjUgNi4yNSw1IEM2LjI1LDcuNSA4LjczMDQ2ODc1LDEwIDExLjIzMDQ2ODgsMTAgTDE1LDEwIEMxNy41LDEwIDIwLDcuNSAyMCw1IEMyMCwyLjUgMTcuNSwwIDE1LDAgTDE1LDAgWiBNNS42MDU0Njg3NSw3LjUgTDUuMDE5NTMxMjUsNy41IEMzLjc1LDcuNSAyLjUxOTUzMTI1LDYuMjUgMi41MTk1MzEyNSw1IEMyLjUxOTUzMTI1LDMuNzUgMy43ODkwNjI1LDIuNSA1LjAxOTUzMTI1LDIuNSBMOC43Njk1MzEyNSwyLjUgQzEwLDIuNSAxMS4yNjk1MzEyLDMuNzUgMTEuMjY5NTMxMiw1IEMxMS4yNjk1MzEyLDUuNDQ5MjE4NzUgMTEuMTMyODEyNSw1Ljg3ODkwNjI1IDEwLjkxNzk2ODgsNi4yNSBMMTMuNTkzNzUsNi4yNSBDMTMuNjkxNDA2Miw1LjgzOTg0Mzc1IDEzLjc1LDUuNDI5Njg3NSAxMy43NSw1IEMxMy43NSwyLjUgMTEuMjY5NTMxMiwwIDguNzY5NTMxMjUsMCBMNSwwIEMyLjUsMCAwLDIuNSAwLDUgQzAsNy41IDIuNSwxMCA1LDEwIEw3LjY5NTMxMjUsMTAgQzYuNzU3ODEyNSw5LjM3NSA1Ljg3ODkwNjI1LDguMjYxNzE4NzUgNS42MDU0Njg3NSw3LjUgTDUuNjA1NDY4NzUsNy41IFoiIGlkPSJTaGFwZSI+PC9wYXRoPgogICAgICAgIDwvZz4KICAgIDwvZz4KPC9zdmc+") no-repeat;
      margin-top: 15px;
      height: 16px;
      width: 20px;
    }

### CSS Icon

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.options = {
      visible: 'always',
      placement: 'left',
      icon: ''
    };
    anchors.add('h3');

    /* See also: nicolasgallagher.com/pure-css-gui-icons */
    .anchorjs-link {
      border-color: #FF5231 #FF5231 transparent;
      border-width: 15px 7px 6px;
      border-style: solid;
      margin-top: 10px;
      font-size: 22px;
      padding-right: 0 !important;
    }

### Emoji

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.options = {
      visible: 'always',
      placement: 'left',
      icon: '⚓'
    };
    anchors.add('p');

    .anchorjs-link {
      margin-left: -1.8em !important;
    }

### Grunticon

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    // Assuming you have set up
    // grunticon and you have a
    // grunticon class named
    // 'icon-grunticon-link'...
    anchors.options = {
      visible: 'always',
      class: 'icon-grunticon-link'
      icon: ''
    };
    anchors.add('h3');

    .anchorjs-link {
      display: inline-block;
      margin-left: 0.375em;
      width: 0.375em;
      height: 20px;
    }

## Hover examples

### Basic Hover

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.add('h3');

### Color Transition

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.add('h3');

    .anchorjs-link:hover {
      color: #2500AD;
    }
    *:hover > .anchorjs-link {
      transition: color .25s linear;
    }

### Shift Out

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.options.placement = 'left';
    anchors.add('h3');

    .anchorjs-link {
      transition: all .25s linear;
    }
    *:hover > .anchorjs-link {
      margin-left: -1.125em !important;
    }

### Arrow

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.options.icon = '# LINK';
    anchors.add('h3');

    /* Based on http://codepen.io/corysimmons/pen/NPBXbe */
    /* Vendor prefixes not included */
    .anchorjs-link {
      position: relative;
      top: 4px;
      height: 36px;
      flex: 1;
      background: #FF5231;
      color: white;
      font-family: Helvetica, Arial, sans-serif;
      font-weight: 200;
      font-size: 1rem;
      margin-right: -6%;
      padding-right: 6%;
      padding-left: 42px !important;
      line-height: 38px;
      transition: all 0.5s ease;
      transform: translateX(100%);
    }
    .anchorjs-link::before {
      position: absolute;
      display: block;
      left: 0;
      width: 0;
      height: 0;
      content: '';
      border: 18px solid #fdfdfd; /* Background color */
      border-right-color: #FF5231;
      transition: all 0.5s ease;
    }
    h2 {
      display: flex;
    }
    *:hover > .anchorjs-link {
      transform: translateX(0);
    }
    *:hover > .anchorjs-link:hover {
      background: #FF806A;
    }
    *:hover > .anchorjs-link:hover::before {
      border-right-color: #FF806A;
    }

### Tooltip

Lorem ipsum dolor consectetur amet nulla elit. Vivamus luctus urna sed urna ultricies. Vivamus luctus urna sed.

{}

    anchors.options = { icon: 'Permalink' };
    anchors.add('h3');

    /* tooltip box */
    .anchorjs-link:after {
      display: inline-block;
      transition: opacity .25s linear;
      font-family: Verdana, sans-serif;
      font-size: 0.75ex;
      font-weight: 100;
      padding: 0.5ex 1.5ex;
      background: #444;
      color: #fff;
      border-radius: 0.6ex;
      vertical-align: 0.8ex;
    }
    /* tooltip arrow */
    .anchorjs-link:before {
      content: '';
      display: inline-block;
      border-top: 0.3ex solid transparent;
      border-right: 0.5ex solid #444;
      border-bottom: 0.3ex solid transparent;
      vertical-align: 0.35ex;
    }
    .anchorjs-link:hover:after {
      background-color: #666;
    }
    .anchorjs-link:hover:before {
      border-right-color: #666;
    }