Top

Usage

The tooltip component must be initialized on an element that will trigger the display of the tooltips, for example.

<a href="/" class="js-tooltip" data-tooltip="This string of text will be displayed in the tooltip.">Help</a>
$('.js-tooltip').tooltip();

The tooltip will display either through a click, or a hover, depending on the configuration.

Dynamic Content Loading

Tooltips use a form of dynamic content loading. This allows the body of the tooltip to be loaded dynamically from multiple sources, either from an AJAX request, an element, or a literal value.

Titles & Content

The titles and content within the tooltip can be customized through the getTitle and getContent options respectively. The values to use will either be extracted from the defined HTML attribute, or through a callback function.

<button type="button" class="js-tooltip" title="Tooltip Title" data-tooltip="/help/text">AJAX</button>
<button type="button" class="js-tooltip" title="Tooltip Title" data-tooltip="#element">DOM</button>

These values use the dynamic content loading mentioned above.

Manual Updates

To programmatically update the tooltip with JavaScript, the show() method on the tooltip instance can be used. When calling show(), an element can be passed as the 1st argument to position the tooltip relative to. If no element is passed, the last element hovered will be used. The 2nd argument is the custom content.

$('#button').toolkit('tooltip', 'show', [null, 'Custom content']);

If we want to update the node and then trigger the tooltip, something like the following can be used. This example assumes that getContent is set to data-tooltip.

var node = $('#button');
    node.data('tooltip', 'New content!').toolkit('tooltip', 'show', node);

Mouse Following

To force the tooltip to follow the location of the mouse, set follow to true.

$('.js-tooltip').tooltip({
    follow: true
});

Notes

  • A className can be added to tooltips during instantiation for different themed tooltips.
  • The position of the tooltip instance determines the location and arrow placement.
  • The position and animation will be appended as a class names.
Top

ARIA

The tooltip role and the appropriate aria-* attributes are required when supporting ARIA. Learn more about this role.

<div class="tooltip" role="tooltip">
    ...
</div>
The JavaScript component will automatically map all ARIA attributes.
Top

Variables

Variable Default Description
$tooltip-tooltip-animations ("fade", "from-above", "from-below", "flip-rotate") A list of all animations to include in the CSS output.
$tooltip-arrow-width 6 The border size for tooltip arrows.
$tooltip-class .tooltip CSS class name for the tooltip wrapper.
$tooltip-class-arrow .tooltip-arrow CSS class name for the tooltip arrow.
$tooltip-class-head .tooltip-head CSS class name for the tooltip header element.
$tooltip-class-body .tooltip-body CSS class name for the tooltip body element.
$tooltip-zindex 700 The z-index for the tooltip element.
Top

Options

Inherits all options from the parent Component.

Option Type Default Description
animation string The animation to use when displaying the tooltip. Available options are: fade, from-above, from-below, flip-rotate.
follow bool false Will position the tooltip relative to the mouse cursor instead of the target element.
getContent string|function data-tooltip If a string is passed, fetch the content from the HTML attribute. If a string is passed in #id format, fetch the content from the HTML of the element. If a function is passed, use the return value as the content.
getTitle string|function title If a string is passed, fetch the content from the HTML attribute. If a function is passed, use the return value as the content.
mode string hover The type of interaction required to activate the tooltip. Accepts click or hover.
mouseThrottle int 50 The time in milliseconds to throttle the mouse follow events.
position string top-center Where to position the tooltip relative to the target element. Available options are: top-left, top-center, top-right, center-left, center-right, bottom-left, bottom-center, bottom-right.
showLoading bool true Show the loading message while waiting for an AJAX request to complete.
showTitle bool true Show the tooltip title alongside the content if available.
template string <div class="tooltip">
<div class="tooltip-inner">
<div class="tooltip-head" data-tooltip-header></div>
<div class="tooltip-body" data-tooltip-content></div>
</div>
<div class="tooltip-arrow"></div>
</div>
The tooltip markup. The data-tooltip-* attributes are required.
wrapperClass string tooltips The class name to set on the composite wrapper.
xOffset int 0 The offset in pixels to move the tooltip along the X axis.
yOffset int 0 The offset in pixels to move the tooltip along the Y axis.
Top

Events

Inherits all events from the parent Component.

Event Arguments Description
load mixed:content, mixed:title Triggered after the tooltip content has been set but before it is shown.
Top

Methods

Inherits all methods from the parent Component.

Method Description Bound To
position(string:content[, string:title]) Position the content relative to the node and set optional content and title. This method is called automatically by show().
show([element:node[, string:content]]) Display the tooltip relative to the node. If no node is passed, will use the last node. If no content is passed, the values will be fetched from the node using the getContent and getTitle options. selector