Tooltip

Examples

View in Pajamas UI Kit →

Structure

1. Container: Wraps the content.
2. Text: Concisely describes the referring element or its purpose.
3. Tip: Points to the referring element.

Guidelines

When to use

• Show the same data in a different format, such as date or timestamps.
• Display a full string of text that is shortened with an ellipsis (…).
• Provide context for unlabeled items such as icon buttons, except for certain cases.

When not to use

• For icon buttons that may be universally understood, like a closing action using the close icon.

Consider using a popover for the following scenarios:

• Display information required for task completion, such as password formatting hints.
• Display more than a single line of information or dimensional data, such as user name or status.
• Display a sophisticated layout and formatting.
• Offer simple controls and/or actions that are closely tied to the element or object, such as searchable list, links, or buttons.

Appearance

• By default, tooltips are placed on top of the referring element.
• When there isn’t enough space in the viewport, the tooltip is moved to the side or below as needed.
• If it blocks related content, the preferred tooltip placement can be manually set.
• Should have no space (0px) between themselves and their target.
• Remain in place while the cursor moves within the target.
• Should never obscure the target element.
• Content within a tooltip uses center-alignment.
• Wraps when the content is wider than the max-width.

Behavior

• Fades in upon hover or focus on the trigger element.
• Remains open until the cursor moves outside of itself or the trigger, or focus is moved away from the trigger.

Tooltip delay

Similar to popovers, a tooltip has a default delay of 500ms on show to help confirm hover intent and ensure that:

• A user doesn’t accidentally hover an element with a tooltip, which might cover an adjacent element they intended to select.
• The UI isn't constantly showing tooltips when a user is moving their mouse over the page.

Overriding the show delay for a tooltip is strongly discouraged for the reasons above, but there are useful circumstances for a tooltip to appear instantly. For example, pipeline icons that are visually the same, but have unique tooltip text that a user relies on to determine the pipeline status. Here, a delay would make it cumbersome to decipher the pipeline while hovering from one icon to the next. To shorten the delay in these cases, utilize ds### in the tooltip directive, where ### is the milliseconds of delay.

Here's an example of a tooltip directive with a 0ms delay (instant) on show:

<gl-button
  v-gl-tooltip.ds0
  ...
/>

Content

• Should be short and concise. Complete sentences are not required.
• Shouldn’t repeat information that is shown near the referring element.

Accessibility

• Tooltips should not auto-dismiss as it would violate WCAG 1.4.13 Content on Hover or Focus
• When adding tooltips, ensure that the element with the tooltip can receive focus so a keyboard user can see the tooltip.
• If the element is a static one, such as an icon, enclose it in a button which already is focusable so we don't have to add tabindex=0 to the icon.

The following code snippet is a good example of an icon with a tooltip.

• It's automatically focusable, as it is a button.
• It's given an accessible name with aria-label, as it is a button with no text.

<button
  v-gl-tooltip
  class="gl-border-0 gl-bg-transparent gl-p-0 gl-leading-0"
  :title="__('Tooltip text')"
  :aria-label="__('Tooltip text')"
>
  <gl-icon name="warning" />
</button>

Code reference

GlTooltip

Using the tooltip component is recommended if you have HTML content. It is also currently required if the tooltip content needs to change while it's visible (see this upstream issue). In all other cases, please use the directive.

Using the component

<gl-button ref="someButton">
  ...
</gl-button>

<gl-tooltip :target="() => $refs.someButton">
  some <em>tooltip<em/> text
</gl-tooltip>

Using the directive

You will need to import and register GlTooltipDirective before you can use it.

<script>
import { GlTooltipDirective } from '@gitlab/ui';

export default {
  directives: {
    GlTooltip: GlTooltipDirective,
  },
};
</script>

<element
  v-gl-tooltip.${modifier}
  title="some tooltip text"
>
  ...
</element>

Directive attributes

v-gl-tooltip directive uses the same attributes as v-b-tooltip.

Under the hood

Tooltip uses <b-tooltip> and v-b-tooltip internally.