Tooltip tooltip.js

Notices

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 .text-nowrap on your <a>s to avoid this behavior.

Examples

Live Demo

Four Directions

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.

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

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>

Pre-generated Tooltip

You can also generate the markup for your tooltip, and then link to it with the target option.

Show Tooltip

×

Sed posuere consectetur est at lobortis.

<button type="button" class="btn btn-info" data-cfw="tooltip" data-cfw-tooltip-target="#tooltipPreGen" data-cfw-tooltip-placement="forward auto">Show Tooltip</button>

<div class="tooltip" id="tooltipPreGen">
  <button type="button" class="close" data-cfw-dismiss="tooltip" aria-label="Close"><span aria-hidden="true">&times;</span></button>
  <div class="tooltip-body">
    <p>Sed posuere consectetur est at lobortis.</p>
    <figure class="figure">
      <img src="/assets/4.4/img/test.gif" class="figure-img img-fluid" alt="Sample image">
      <figcaption class="figure-caption text-light">Sample image caption.</figcaption>
    </figure>
  </div>
  <div class="tooltip-arrow"></div>
</div>

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 tooltip-viewport-bottom" title="This should be shifted to the right">Shift Right</button>
  <button type="button" class="btn tooltip-viewport-right" title="This should be shifted down">Shift Down</button>
  <button type="button" class="btn float-end tooltip-viewport-bottom" title="This should be shifted to the left">Shift Left</button>
  <button type="button" class="btn 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>, ideally made keyboard-focusable using tabindex="0".

<span class="d-inline-block" tabindex="0" data-cfw="tooltip" title="Tooltip for disabled item">
  <button class="btn btn-primary" 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

Toggle

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.

Dismiss

Dismissal can be achieved with data-cfw-dismiss attributes on a button within the tooltip as demonstrated below:

<button type="button" class="close" data-cfw-dismiss="tooltip" aria-label="Close"><span aria-hidden="true">&times;</span></button>

or on a button outside the tooltip using the additional data-cfw-tooltip-target as demonstrated below:

<button type="button" class="close" data-cfw-dismiss="tooltip" data-cfw-tooltip-target="#myTooltip">Close tooltip</button>

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
}

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

Methods

Method calls can be made on either the trigger or the target <div class="tooltip"> element.

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

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. Additionally, do not rely solely on hover as the trigger for your tooltips as this will make them impossible to trigger for keyboard users.

Key Commands

The following key commands are handled when focus is inside the toolip, or on the tooltip trigger:

• Esc - Close the tooltip

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.

SASS Reference

Variables

The available Customization options, or Sass variables, that can be customized for the tooltip component.

Mixins

No mixins available.