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.
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!
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.
Compiled and minified CSS and JavaScript. No docs or original source files are included.
Source Less and JavaScript files, along with this documentation. Requires a Less compiler and some setup.
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
:
The alternative or manual method is to invoke the plugin based on a set of selectors:
Anchors require the tooltip plugin to be included in your version of Bootstrap.
For performance reasons, the Tooltip, Popover and Anchor data-apis are opt-in, meaning you must initialize them yourself.
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
.
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.
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.
[data-anchor]
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 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.
Name | Details |
---|---|
anchors | Determines if the target element is considered an "anchor". If the plugin is bound to the 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 |
anchorContainer |
boolean | string |
anchorDuration |
number |
anchorFindNamed | Searches for any nearby deprecated named anchors ( 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 If no named anchor is found, then the plugin will proceed to auto-generate an ID for the anchor (if enabled). boolean Potential performance impactEnabling this option can decrease performance. It requires the plugin to traverse and manipulate the DOM when no existing |
anchorGenerateId | If the target element is considered an anchor and does not have an 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 |
anchorHistory |
string | false |
anchorIcon |
string | false |
anchorIgnore |
string |
anchorLinks | Determines if the target element is considered an "anchor link". If the plugin is bound to the 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 |
anchorNormalizeId | Normalizes generated anchor IDs to be more human readable and consistent with other anchors on the page. To disable all normalizations, pass object | false Dependent optionThis option is only taken into account if the |
anchorOffset |
number |
anchorPrefix |
string | false |
anchorTarget |
string | false |
anchorUnique |
boolean |
placement | How to position the anchor tooltip - top | bottom | left | right | auto. 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 string | function |
scrollOnHashchange |
boolean |
scrollOnLoad |
boolean |
template | Base HTML to use when creating the anchor tooltip. The anchor tooltip's string |
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 |
viewport | Keeps the anchor tooltip within the bounds of this element. Example: object | string |
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.
Name | Details |
---|---|
animation | Apply a CSS fade transition when showing or hiding the anchor tooltip upon hovering on the anchor. boolean |
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: number | object |
The following inherited Tooltip options are completely ignored by the Anchor plugin.
Name | Reason |
---|---|
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 |
title | An anchor tooltip uses an icon for its content. |
$.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')
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 |