Tooltip tooltip.js

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, forward (right), bottom, and reverse (left) aligned.

Heads up! When using the right-to-left, rtl, variant of Figuration all horizontal directions will be reversed. Meaning left becomes right, and vice-versa.

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="forward" title="Forward tooltip">
  Forward tooltip
</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="reverse" title="Reverse tooltip">
  Reverse tooltip
</button>

Live Demo

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="forward" 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="forward" 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: 'forward',
  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.

<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-end 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: 'forward',
    viewport: '#viewport-tooltip',
    padding: 2
  });
  $('.tooltip-viewport-bottom').CFW_Tooltip({
    placement: 'bottom',
    viewport: '#viewport-tooltip',
    padding: 2
  });
</script>

Disabled Elements

Elements with the disabled attribute aren't interactive, meaning users cannot hover or click them to trigger a tooltip (or popover). As a workaround, you'll want to trigger the tooltip from a wrapper <div> or <span> and override the pointer-events on the disabled element.

<span class="d-inline-block" data-cfw="tooltip" title="Tooltip for disabled item">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>

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).

If the tooltip item is already created, you can link to it using data-cfw-tooltip-target="#someTooltip", or href="#someTooltip". The proper role and aria- attributes will be automatically created to link the trigger and target elements.

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="forward".

function myTipAlign(tip, trigger) {
  // this - tooltip data-api
  // tip -> tooltip target
  // trigger -> tooltip trigger
}

Methods

.CFW_Tooltip(options)

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

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

.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.

.CFW_Tooltip('unlink')

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

.CFW_Tooltip('dispose')

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

Events

Event callbacks happen on the toggle/trigger element.

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

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('dispose');
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), the trigger becomes focused, the next forward focus will move from the trigger to the first focusable item inside 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 trigger.

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