- 
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-jsor 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;
-}
-