Skip to main content

The missing Bootstrap plugin for anchor support.

Download Bootstrap Anchor

Currently v0.0.2


This plugin and documentation is currently under development. Please ignore any missing or contradicting information!

Anchors bootstrap-anchor.js

Add tooltips containing a link to the anchor, like those on GitHub READMEs, to any element for direct access, bookmark or scrolling.

Anchors that have no id attribute and no text content to generate one are never displayed.

Unofficial Bootstrap Plugin

The Bootstrap Anchor plugin and its documentation (this site) is not officially associated with the Bootstrap project in any way.

Similarities in site styling and presentation should be credited to the many authors of the original Bootstrap Documentation site.

There is an issue to potentially merge this plugin upstream into Bootstrap. If you find this plugin invaluable, voice your support!

Download

Bootstrap Anchor (currently v0.0.2) has a few easy ways to quickly get started, each one appealing to a different skill level and use case. Read through to see what suits your particular needs.

Distribution

Compiled and minified CSS and JavaScript. No docs or original source files are included.

Download Bootstrap Anchor

Source code

Source Less and JavaScript files, along with this documentation. Requires a Less compiler and some setup.

Download source

Usage

The anchor plugin generates content and markup on demand, and places anchor tooltips inside their trigger element.

There are two ways to initialize the anchor plugin via JavaScript.

The highly recommended method is to bind the plugin directly to document:

+function ($) {
  $(document).anchor()
}(jQuery)

The alternative or manual method is to invoke the plugin based on a set of selectors:

+function ($) {
  $(document).ready(function () {
    // Initialize anchors on select elements.
    $('h1.page-header, .anchor').anchor()
  })
}(jQuery)

Plugin dependency

Anchors require the tooltip plugin to be included in your version of Bootstrap.

Opt-in functionality

For performance reasons, the Tooltip, Popover and Anchor data-apis are opt-in, meaning you must initialize them yourself.

Document Binding

It is not necessary to instantiate the plugin inside a $.ready() wrapper when binding to the document. The plugin will automatically do this for you, if necessary.

If needed, for code sanity, the plugin can alternatively be bound to window, 'html' or 'body'. The plugin considers these top level DOM elements and will reset to always bind document.

Excluding elements

If automatically binding to the DOM, any elements that match the exclude option will always be ignored. This applies to both anchors and anchor links. This option can be disabled by passing an empty string or false.

If manually instantiating anchors or anchor links, you must also manually filter the returned elements (usually with .not()) before continuing to instantiate the plugin.

Examples

This entire page is an example! Hover over the headings below to view the anchor tooltip. The second part of the plugin handles links clicks to anchors and scrolls to them. You can view this functionality in the sidebar to the right.

Auto-generated anchors

Heading 1

Heading 2

Heading 3

Heading 4

[data-anchor]
<div class="row">
  <div class="col-sm-11 col-sm-offset-1">
    <h1>Heading 1</h1>
    <h2>Heading 2</h2>
    <h3>Heading 3</h3>
    <h4>Heading 4</h4>
    <kbd data-anchor="true">[data-anchor]</kbd>
  </div>
</div>

Right aligned anchors

Heading 1

Heading 2

Heading 3

Heading 4

[data-anchor]
<div class="row">
  <div class="col-sm-11 text-right">
    <h1 data-placement="auto right">Heading 1</h1>
    <h2 data-placement="auto right">Heading 2</h2>
    <h3 data-placement="auto right">Heading 3</h3>
    <h4 data-placement="auto right">Heading 4</h4>
    <code data-anchor="true" data-placement="auto right">[data-anchor]</code>
  </div>
</div>

Viewport detection

If the anchor's viewport option/element (BODY by default) has any top margin or padding, the plugin will automatically adjust the anchor's top position when scrolling to it.

Current navbar: fixed

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-animation="false".

Note: If the plugin is bound to a link and the link finds a matching anchor, it delegates the scrolling to the anchor's instance. This allows anchors (h1, h2, h3, etc.) to individual override to specific options, should the need arise.

NameDetails
anchors

Determines if the target element is considered an "anchor". If the plugin is bound to the document, these are the selectors used to delegate bindings for anchors.

If no option was specified, but the plugin was initialized on normal elements, the selector used will override this option. See Usage for more details.

string
'h1,h2,h3,h4,[data-anchor]'
anchorContainer

@todo Document this

boolean | string
true
anchorDuration

@todo Document this

number
300
anchorFindNamed

Searches for any nearby deprecated named anchors (<a name="..."></a>) to use as the anchor ID if the target element has no id attribute present.

If enabled, the plugin looks for the first named anchor sibling that immediately precedes or follows the target element.

If no sibling named anchor is found, the plugin will instead look for the first available named anchor child inside the target element.

If a named anchor is found, its name attribute will be used as the anchor ID and the found named anchor element will be removed from the DOM.

If no named anchor is found, then the plugin will proceed to auto-generate an ID for the anchor (if enabled).

boolean
false

Potential performance impact

Enabling this option can decrease performance. It requires the plugin to traverse and manipulate the DOM when no existing id attribute is found on the target element. Only enable this option if existing named anchors are known to exist or the majority of the anchor selectors will have an existing ID.

anchorGenerateId

If the target element is considered an anchor and does not have an id attribute (or name attribute if the element is <a>), then an anchor ID can automatically be generated by the text contents of the target element.

If the target element does not have any text content and no ID can be generated, then the anchor is considered to be invalid and will not be shown.

boolean
true
anchorHistory

@todo Document this

string | false
'append'
anchorIcon

@todo Document this

string | false
'<span class="glyphicon glyphicon-link" aria-hidden="true"></span>'
anchorIgnore

@todo Document this

string
'[data-anchor-ignore]:not([data-anchor-ignore="false"]),[data-dismiss],[data-slide],[data-toggle]:not([data-toggle="anchor"])'
anchorLinks

Determines if the target element is considered an "anchor link". If the plugin is bound to the document, these are the selectors used to delegate bindings for anchor links.

If no option was specified, but the plugin was initialized on normal elements, the selector used will override this option. See Usage for more details.

string | false
'a[href*="#"],[data-toggle="anchor"]'
anchorNormalizeId

Normalizes generated anchor IDs to be more human readable and consistent with other anchors on the page.

To disable all normalizations, pass false to the entire option.

object | false
!{
  // The character to use when converting or replacing characters.
  separator: '-', // string | ''

  // The following options appear in the order they are executed.

  // Places a separator before uppercase letters.
  convertCamel: true, // boolean

  // Converts the case.
  convertCase: 'lower', // 'upper' | 'lower' | false

  // Converts matching characters to the separator.
  convert: /[\s_.(){}\[\]]/g, // RegExp | string | false

  // Removes matching characters, in this case: non-alphanumeric.
  strip: /[^\w-]/gi, // RegExp | string | false

  // Ensures no concurrent separators (i.e. some--id).
  singleSeparator: true, // boolean

  // Trims beginning and ending separators (i.e. -some-id-).
  trim: true, // boolean

  // Limits length of the final ID.
  maxLength: 32 // number | false
}
          

Dependent option

This option is only taken into account if the anchorGenerateId option is enabled.

anchorOffset

@todo Document this

number
20
anchorPrefix

@todo Document this

string | false
false
anchorTarget

@todo Document this

string | false
false
anchorUnique

@todo Document this

boolean
true
placement

How to position the anchor tooltip - top | bottom | left | right | auto.
When "auto" is specified, it will dynamically reorient the anchor tooltip. For example, if placement is "auto left", the anchor tooltip will display to the left when possible, otherwise it will display right.

When a function is used to determine the placement, it is called with the tooltip DOM node as its first argument and the triggering element DOM node as its second. The this context is set to the tooltip instance.

string | function
'auto left'
scrollOnHashchange

@todo Document this

boolean
true
scrollOnLoad

@todo Document this

boolean
true
template

Base HTML to use when creating the anchor tooltip.

The anchor tooltip's icon option will be injected into the link (a element).

string
'<span class="anchor-link" role="tooltip"><a href="#anchor"></a></span>'
trigger

How anchor tooltips and links are triggered - click | hover | focus | manual.

If a string is supplied, the trigger is applied to both anchors and anchor links.

You may pass multiple triggers; separate them with a space.

object | string
!{
  anchors: 'hover focus',
  links: 'click'
}
          
viewport

Keeps the anchor tooltip within the bounds of this element. Example: viewport: '#viewport' or { "selector": "#viewport", "padding": 0 }

object | string
!{
  selector: 'body',
  padding: 0
}
          

Inherited options

The following options are inherited from the Tooltip plugin. Bootstrap Anchor does not override any defaults set for these options. The defaults below are assumptions based on the original code of the Tooltip plugin. Their actual default value may change based on any existing site configuration.

NameDetails
animation

Apply a CSS fade transition when showing or hiding the anchor tooltip upon hovering on the anchor.

boolean
true
delay

Delay showing and hiding the anchor tooltip (ms) - does not apply to manual trigger type

If a number is supplied, delay is applied to both hide/show

Object structure is:

!{
  show: 500,
  hide: 100
}
          
number | object
0

Ignored options

The following inherited Tooltip options are completely ignored by the Anchor plugin.

NameReason
container

Anchor tooltips are always attached directly to the anchor. This is needed for relative positioning so the anchor tooltip does not disappear.

html

An anchor tooltip uses an icon for its content. It always inserts the icon option using the $.html() method.

title

An anchor tooltip uses an icon for its content.

Methods

$.anchor(options)

Attaches a anchor tooltip handler to an element collection.

$.anchor('show')

Reveals an element's anchor tooltip. Returns to the caller before the anchor tooltip has actually been shown (i.e. before the shown.bs.anchor event occurs). This is considered a "manual" triggering of the anchor tooltip. Anchors with no id are never displayed.

$('#element').anchor('show')

$.anchor('hide')

Hides an element's anchor tooltip. Returns to the caller before the anchor tooltip has actually been hidden (i.e. before the hidden.bs.anchor event occurs). This is considered a "manual" triggering of the anchor tooltip.

$('#element').anchor('hide')

$.anchor('toggle')

Toggles an element's anchor tooltip. Returns to the caller before the anchor tooltip has actually been shown or hidden (i.e. before the shown.bs.anchor or hidden.bs.anchor event occurs). This is considered a "manual" triggering of the anchor tooltip.

$('#element').anchor('toggle')

$.anchor('destroy')

Hides and destroys an element's anchor tooltip. Anchor that are delegated (when they are are created using the selector option) cannot be individually destroyed on descendant trigger elements.

$('#element').anchor('destroy')

$.anchor('scrollTo')

@todo Document this

$('#element').anchor('scrollTo')

Events

Event Type Description
show.bs.anchor This event fires immediately when the show instance method is called.
shown.bs.anchor This event is fired when the anchor tooltip has been made visible to the user (will wait for CSS transitions to complete).
hide.bs.anchor This event is fired immediately when the hide instance method has been called.
hidden.bs.anchor This event is fired when the anchor tooltip has finished being hidden from the user (will wait for CSS transitions to complete).
scroll.bs.anchor @todo Document this
scrolled.bs.anchor @todo Document this