Skip Navigation

Tooltips

Tooltips are brief labels that may be displayed when the user hovers over a link, button or icon on desktop.


When to Use

  • Use in desktop applications to provide brief help text related to a link, button, icon or similar element on a screen.
  • Tooltips are best suited to desktop applications where users are more likely to be using a mouse. For touch contexts it is not recommended to rely too heavily on this pattern.
  • Use when you need to provide more than ALT-attribute text for images.

When Not to Use

  • Do not use when you need to display additional detailed content such as images, formatted text and/or form elements. Instead, use a Popover.

Usage

Tooltips usually appear on top of the element centered at a 5px margin of space from element. They can also appear top, right, bottom or left. They have directional arrows that convey direction from the source.

For more complex content, consider using a Popover or a Modal.

Developer Notes

Tooltips are created by adding the spark-tooltip class to an element. When this element is hovered over, content will be shown. The content is created using a class of spark-tooltip__content--top, spark-tooltip__content--bottom, spark-tooltip__content--left or spark-tooltip__content--right. These different content classes determine the position of the tooltip.

The following options may be passed when using new Spark.Tooltip(el, {});:

Name Type Default Description
anchorX string 'center' The default x-axis alignment of the tooltip. Can also be defined using the data-anchor-x attribute on the tooltip toggle element.
anchorY string 'bottom' The default y-axis alignment of the tooltip. Can also be defined using the data-anchor-y attribute on the tooltip toggle element.
contentEl element null The element to use for the tooltip content. This will be shown when the toggle is clicked.
toggleEl element null The element to use for the tooltip toggle.

For all available methods and full API, refer to the component code on Bitbucket.

<button class="spark-btn--icon spark-icon spark-icon-cog spark-tooltip" aria-label="Settings" aria-expanded="false" aria-describedby="tooltip1">
  <span id="tooltip1" class="spark-tooltip__content--left" role="tooltip">
    Change your settings
    <span class="spark-tooltip__caret"></span>
  </span>
</button>

<button class="spark-btn--icon spark-icon spark-icon-cog spark-tooltip" aria-label="Settings" aria-expanded="false" aria-describedby="tooltip1">
  <span id="tooltip2" class="spark-tooltip__content--top" role="tooltip">
    Change your settings
    <span class="spark-tooltip__caret"></span>
  </span>
</button>

<button class="spark-btn--icon spark-icon spark-icon-cog spark-tooltip" aria-label="Settings" aria-expanded="false" aria-describedby="tooltip1">
  <span id="tooltip3" class="spark-tooltip__content--bottom" role="tooltip">
    Change your settings
    <span class="spark-tooltip__caret"></span>
  </span>
</button>

<button class="spark-btn--icon spark-icon spark-icon-cog spark-tooltip" aria-label="Settings" aria-expanded="false" aria-describedby="tooltip1">
  <span id="tooltip4" class="spark-tooltip__content--right" role="tooltip">
    Change your settings
    <span class="spark-tooltip__caret"></span>
  </span>
</button>

<style type="text/css">
  
</style>
// Vanilla JS
var el = document.querySelector('.spark-tooltip');
var tooltipInstance = new Spark.Tooltip(el);

Accessibility Notes

As defined earlier, the Tooltip component should be used with links, buttons, icons and similar elements. The examples provided in the Developer tab use Icon Buttons as the elements the Tooltips are connected to. To make them fully accessible, the examples have been enhanced as follows:

  • An aria-label attribute has been added to the button element to provide text that can be accessed by screen-readers and assistive devices. This is done because the span containing the tooltip is re-positioned in the DOM using Javascript when the tooltip is displayed, and is no longer inside the button element at that point. The icon displayed is also displayed using pseudo-elements and as such do not have text that can be accessed either.

  • An aria-expanded attribute has been added to the button element to indicate the initial state of the tooltip. Javascript is used to toggle this from false to true when the tooltip is displayed.

  • An aria-describedby attribute creates the relationship between the button element and the tooltip container by indicating that the description of the button will come from the tooltip text. The value of this attribute is the id of the tooltip element. If you have multiple tooltips in use, ensure that the ids used are unique across the page.

  • Note that the tooltip container has a role defined as tooltip to indicate to assistive technologies that this is a tooltip element.