Tooltip tooltip.js

Add stylized tooltips to items for contextual or informational support.

Notices

Widget Dependencies

Tooltip requires the following:

  • The third-party library Popper.js to provide dynamic positioning and viewport detection.

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

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.

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>

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

Name Type Default Description
target string null The selector of the target tooltip.
animate boolean true If tooltip items should fade in and out.
placement string | object | function 'top'

string:
How to position the tooltip - top | bottom | reverse | forward| auto.
When "auto" is specified with a directional value, it will dynamically reorient the tooltip. For example, if placement is "auto reverse", the tooltip will display to the left when possible, otherwise it will display right. (Opposite horizontal directions apply for rtl mode.) When just "auto" is specified, a best fit approach will be used.

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 | element | function 'scrollParent'

Keep the tooltip within the bounds of this element. Example: viewport: '#viewport'.

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.

This option maps to the .boundariesElement option in Popper.js, so it will accept values of 'viewport', 'window', 'scrollParent', or an HTMLElement reference (JavaScript only). For more information refer to Popper.js's preventOverflow docs.

padding integer 0 Spacing, in pixels, to keep the tooltip away from the viewport edge.
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'
target string null The selector of the target tooltip.
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.
dispose boolean false If the dispose method should be called when the tooltip is hidden. This will remove the tooltip from the DOM.
show boolean false Show the tooltip automatically at the end of initialization. This will force the trigger option to a setting of 'click'.
popperConfig null | object null Pass a customized Popper.js configuration that will override the default Popper.js configuration.
$('#myTooltip').CFW_Tooltip({
placement: 'forward'
});

Methods

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

Method Name Description
toggle Toggles a tooltip item to be shown or hidden.
show Shows an element's tooltip.
hide Hides an element's tooltip.
locateUpdate Update the positioning of a tooltip. Can be useful after an AJAX content update.
unlink Hides the tooltip, removes events and attributes from both trigger and tooltip.
dispose Calls the unlink method, and then removes the tooltip from the DOM.
$('#myTooltip').CFW_Tooltip('show');

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.
dispose.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('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.

SASS Reference

Variables

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

Name Type Default Description
$enable-tooltip boolean true Enable the generation of the tooltip component classes. Smaller segements of the tooltip component classes can be disabled with the following $enable-* variables.
$enable-tooltip-arrow boolean true Enable the generation tooltip arrows classes.
$enable-tooltip-body boolean true Enable the generation tooltip body class.
$enable-tooltip-close boolean true Enable the generation tooltip close button class.
$tooltip-max-width string rem(208px) (13rem) Max width for tooltip container.
$tooltip-padding-y string .25rem Vertical padding for tooltip body.
$tooltip-padding-x string .5rem Horizontal padding for tooltip body.
$tooltip-padding-x string .5rem Horizontal padding for tooltip body.
$tooltip-margin string .125rem Spacing offset for tooltip container.
$tooltip-font-size string ($font-size-base * .875) Font size for tooltip container.
$tooltip-bg string $uibase-900 Background color for tooltip body.
$tooltip-color string color-auto-contrast($uibase-900) Text color for tooltip body.
$tooltip-opactity string .9 Opacity for tooltip container.
$tooltip-border-radius string $border-radius Border radius for tooltip body.
$tooltip-close-padding-y string .125rem Vertical padding for tooltip close button.
$tooltip-close-padding-x string .3125rem Horizontal padding for tooltip close button.
$tooltip-close-color string $tooltip-color Text color for tooltip close button.
$tooltip-close-opacity string $close-opacity Opacity for tooltip close button.
$tooltip-close-hover-color string $tooltip-color Text color for tooltip close button in hover and focus states.
$tooltip-close-hover-opacity string $close-hover-opacity Opacity for tooltip close button in hover and focus states.
$tooltip-arrow-width string .75rem Width for tooltip arrow, when placed on top or bottom. Height when used on sides.
$tooltip-arrow-height string .375rem Height for tooltip arrow, when placed on top or bottom. Width when used on sides.
$tooltip-arrow-color string $tooltip-bg Background color for tooltip arrow.

Mixins

No mixins available.