Skip to main content
Figuration v3 Preview Available!
Widgets

Bring interactivity to your site with a selection of jQuery widgets (plugins) all built with accessibility and usability in mind.

Tooltip tooltip.js

Contents

Overview

Important notes about using the tooltip widget:

  • Specify container: 'body' to avoid rendering problems in more complex components (like our input groups, button groups, etc).
  • Triggering tooltips on hidden elements will not work.
  • Tooltips for .disabled or disabled elements must be triggered on a wrapper element.
  • When triggered from hyperlinks that span multiple lines, tooltips will be centered. Use white-space: nowrap; on your <a>s to avoid this behavior.

Examples

Static Tooltip

Four options are available: top, right, bottom, and left aligned.

Four Directions

<button type="button" class="btn" data-cfw="tooltip" data-cfw-tooltip-container="body" data-cfw-tooltip-placement="top" title="Tooltip on top">
    Tooltip on top
</button>

<button type="button" class="btn" data-cfw="tooltip" data-cfw-tooltip-container="body" data-cfw-tooltip-placement="right" title="Tooltip on right">
    Tooltip on right
</button>

<button type="button" class="btn" data-cfw="tooltip" data-cfw-tooltip-container="body" data-cfw-tooltip-placement="bottom" title="Tooltip on bottom">
    Tooltip on bottom
</button>

<button type="button" class="btn" data-cfw="tooltip" data-cfw-tooltip-container="body" data-cfw-tooltip-placement="left" title="Tooltip on left">
    Tooltip on left
</button>

Live Demo

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi a arcu felis. Ut vulputate quis lectus id tristique. Donec mattis justo eu turpis facilisis interdum. Nulla facilisi. Suspendisse potenti. In lobortis, est ut aliquam blandit, felis lacus tempor magna, nec pharetra libero odio nec enim.

Toggle Example

<button type="button" class="btn btn-info" data-cfw="tooltip" title="Click the trigger or close button to close me." data-cfw-tooltip-placement="right" data-cfw-tooltip-trigger="click">Click to toggle tooltip</button>

Tooltip with HTML

<button type="button" class="btn btn-info" data-cfw="tooltip" data-cfw-tooltip-html="true" data-cfw-tooltip-placement="right" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">Tooltip with HTML</button>

When using more complex HTML, using a data attribute might not be optimal. A better option would be to use the Javascript options.

<button type="button" class="btn btn-info" id="html-tooltip">Tooltip with HTML</button>

<script>
$('#html-tooltip').CFW_Tooltip({
    html: true,
    placement: 'right',
    title: '<span aria-hidden="true">&middot;</span> <em>Tooltip</em> <u>with</u> <b>HTML</b>'
});
</script>

Viewport Constrainment

Keep tooltips in their place with the viewport option.

Test viewport constraints for tooltips.

<div class="container-viewport" id="viewport-tooltip">
    <p class="viewport-text">Test viewport constraints for tooltips.</p>

    <button type="button" class="btn btn-default tooltip-viewport-bottom" title="This should be shifted to the right">Shift Right</button>

    <button type="button" class="btn btn-default tooltip-viewport-right" title="This should be shifted down">Shift Down</button>

    <button type="button" class="btn btn-default float-right tooltip-viewport-bottom" title="This should be shifted to the left">Shift Left</button>

    <button type="button" class="btn btn-default tooltip-viewport-right btn-bottom" title="This should be shifted up">Shift Up</button>
</div>
<script>
    $('.tooltip-viewport-right').CFW_Tooltip({
        placement: 'right',
        viewport: {selector: '#viewport-tooltip', padding: 2}
    });
    $('.tooltip-viewport-bottom').CFW_Tooltip({
        placement: 'bottom',
        viewport: {selector: '#viewport-tooltip', padding: 2}
    });
</script>

Usage

The tooltip widget, by default, generates content and markup on demand, and by default places tooltips after their trigger element.

Via Data Attributes

The required markup for a tooltip is only a data-cfw="tooltip" attribute and title on the HTML element you wish to have a tooltip. The generated markup of a tooltip is rather simple, though it does require a position (by default, set to top by the widget).

Via JavaScript

Enable manually with:

$('#myTooltip').CFW_Tooltip();

Close Triggers

Any element with a data attribute of data-cfw-dismiss="tooltip" within the tooltip element will act as a close trigger for the tooltip.

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-cfw-tooltip, as in data-cfw-tooltip-placement="right".

Name Type Default Description
toggle string null Either the selector (jQuery style), or the string related to the target tooltip having a data-cfw-tooltip-target attribute.
animate boolean true If tooltip items should fade in and out.
speed integer 150 Speed of animation (milliseconds) - corresponds the animation speed specified in CSS.
follow boolean false If browser focus should move when a tooltip is activated - overridden to true when click trigger is used.
placement string | object | function 'top'

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

object:
This is a way to custom position a tooltip in a specific place not handled by the standard placement locations. A custom positioned tooltip is forced to using the <body> as the container to make positioning easier. Object structure is: placement: { top: 5, left: 10 }, the same as jQuery offset.

function:
A function call can return either a string or object placement type. The function allows access to the complete tooltip data-api, as well as passing the tooltip target and trigger as arguments.

function myTipAlign(tip, trigger) {
    // this - tooltip data-api
    // tip -> tooltip target
    // trigger -> tooltip trigger
}
trigger string 'hover focus' How tooltip is triggered - click | hover | focus | manual. You may pass multiple triggers; separate them with a space. manual cannot be combined with any other trigger.
delay number| object show:0, hide:250

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

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

Object structure is: delay: { show: 500, hide: 100 }
container string | false false Appends the tooltip to a specific element. Example: container: 'body'
viewport string | object | function { selector: 'body', padding: 0 }

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

If a function is given, it is called with the triggering element DOM node as its only argument. The this context is set to the tooltip instance.

html boolean false

Allow HTML in the tooltip.

If false, jQuery's text method will be used to insert content into the DOM. Use text if you're worried about XSS attacks.

closetext string '<span aria-hidden="true" >&times;</span>' Visible text for close links when using option trigger: 'click'
closesrtext string 'Close' Screen reader only text alternative for close links when using option trigger: 'click'
toggle string null

If the tooltip item is already created, you can link to it using data-cfw-tooltip-toggle="someTooltip".

The target tooltip item will then need the associated attribute data-cfw-tooltip-target="someTooltip".

The proper role and ARIA attributes will be automatically created to link the trigger and target elements.

title string | function '' Default title value if title attribute isn't present.
unlink boolean false If the unlink method should be called when the tooltip is hidden. This leaves the tooltip behind in the DOM.
destroy boolean false If the destroy method should be called when the tooltip is hidden. This will remove the tooltip from the DOM.
activate boolean false Show the tooltip automatically at the end of initialization. This will force the trigger option to a setting of 'click'.

Methods

.CFW_Tooltip(options)

Activates a tooltip on a given element. Accepts an optional options object.

$('#myTooltip').CFW_Tooltip({
    placement: 'right'
});

.CFW_Tooltip('toggle')

Toggles a tooltip item to be shown or hidden.

.CFW_Tooltip('show')

Shows an element’s tooltip.

.CFW_Tooltip('hide')

Hides an element’s tooltip.

Hides the tooltip, removes events and attributes from both trigger and tooltip.

.CFW_Tooltip('destroy')

Calls the unlink method, and then removes the tooltip from the DOM.

Events

Event callbacks happen on the toggle/trigger element.

Event Type Description
init.cfw.tooltip This event fires after the tooltip item is initialized.
beforeShow.cfw.tooltip This event is fired immediately when the show method is called. If the tooltip container is not present, it is created just after this event is called.
afterShow.cfw.tooltip This event is fired when a tooltip has been made visible to the user (will wait for CSS transitions to complete).
beforeHide.cfw.tooltip This event is fired immediately when the hide method is called.
afterHide.cfw.tooltip This event is fired when a tooltip has been hidden from the user (will wait for CSS transitions to complete).
inserted.cfw.tooltip This event is fired after the beforeShow.cfw.tooltip event when the tooltip has been added to the DOM.
beforeUnlink.cfw.tooltip This event is fired immediately when the unlink method is called. This event can occur after the beforeHide event if set to automatically unlink, or before if called via method.
afterUnlink.cfw.tooltip This event is fired when a tooltip item has been unlinked from its trigger item and the data-api removed. This event can occur after the afterHide event when invoked from the unlink method, or before if set to automatically unlink.
destroy.cfw.tooltip This event is fired immediately before the tooltip item is removed from the DOM.

$('#myTooltip').on('afterHide.cfw.tooltip', function () {
  // do something&hellip;
});

Server-side Apps

Tooltips are designed to hopefully work with server side applications, such as Apache Wicket, and other instances where the server-side application might need to create or update the tooltip content after the initial page load.

A quick example:

  1. An item with an event handler that makes a callback to create a new tooltip is interacted with.
  2. Call as needed:
    • $('#myTooltip').CFW_Tooltip('hide');
    • or $('#myTooltip').CFW_Tooltip('unlink');
    • or $('#myTooltip').CFW_Tooltip('destroy');
  3. Update/create the tooltip object and insert into DOM.
  4. Initialize the tooltip: $('#myTooltip').CFW_Tooltip(options); with desired options.
  5. Show tooltip: $('#myTooltip').CFW_Tooltip('show');

Accessibility

Consider Keyboard and Assistive Technology Users

You should only add tooltips to HTML elements that are traditionally keyboard-focusable and interactive (such as links or form controls). Although arbitrary HTML elements (such as <span>s) can be made focusable by adding the tabindex="0" attribute, this will add potentially annoying and confusing tab stops on non-interactive elements for keyboard users. In addition, most assistive technologies currently do not announce the tooltip in this situation.

Key Commands

The following key commands are handled when focus is inside the toolip:

  • Esc - Close the tooltip (when using trigger: click)

Focus Handling

Tooltips have additional focus handling when using keyboard navigation.

If navigating from above the tooltip’s trigger (typically with the tab key), when the trigger becomes focused, focus will be moved from the trigger to the top of the tooltip.

If navigating from below the tooltip’s trigger (typically with the shift-tab key combination), when the trigger is focused, focus will be moved from the trigger to the last focusable item inside the tooltip.

When navigating forward, out the bottom of the tooltip, the focus will be moved to the next focusable item in the document relative to the trigger. This is done so that if the container option is used, the focus will move to next logical item. Otherwise, when using container: body, the focus will potentially drop off the end of the HTML document, leaving a keyboard user in an akward situation.

When navigating backward, out the top of the tooltip, the focus will be moved to the preceding focusable item in the document relative to the trigger.

This will not necessarily work with some assistive technologies reading modes.