Tooltip

When to use

Explanations for unfamiliar terms or jargon

Tooltips can offer brief definitions or explanations for technical terms, acronyms, or industry-specific terminology.

Long titles or descriptions

If you’re displaying a list of articles with truncated titles, a tooltip can reveal the complete title when users hover over the ellipsis.

When not to use

Essential and critical information

Avoid using tooltips for critical instructions or essential information. Users may miss tooltips, especially if they quickly interact with elements.

Mobile devices and touchscreens

Tooltips rely on hover interactions, which do not translate well to touchscreens.

Accessibility concerns

Some users rely on screen readers or have visual impairments. Ensure that tooltips are accessible and provide an alternative method (such as keyboard shortcuts) to access the same information.

Anatomy

Figma Options

With these options you can tweak the appearance of the tooltip in Figma. They are available in the Design Panel so you can compose the tooltip to exactly fit the user experience need for the uses case you are working on.

Label or description

Use type to control how the tooltip is linked for screen readers. The default, label, exposes the tooltip as the accessible name of the anchor and is what you want for icon-only buttons. Use type="description" when the anchor already has its own label and the tooltip only adds extra information.

<sl-button id="edit" fill="outline"><sl-icon name="far-pen"></sl-icon></sl-button>
<sl-tooltip for="edit">Edit</sl-tooltip>

<sl-button id="publish" fill="solid" variant="primary">Publish</sl-button>
<sl-tooltip for="publish" type="description">Makes the page visible to everyone</sl-tooltip>

You don't have to add aria-labelledby or aria-describedby yourself; the tooltip sets the relation on every anchor it belongs to, and removes it again when it is disabled or removed. See the accessibility page for more about this.

Triggers

By default the tooltip shows when the user hovers over the anchor or focuses it with the keyboard. Use trigger to change that; it takes a space separated list of hover, focus and click. Use manual when the tooltip should only be shown programmatically.

<sl-button id="click-trigger">Click me</sl-button>
<sl-tooltip for="click-trigger" trigger="click" type="description">Click the button again to dismiss me</sl-tooltip>

A few details worth knowing:

• Focusing the anchor with the mouse does not show the tooltip; only keyboard focus (:focus-visible) does. That way the tooltip stays out of the way when a dialog returns focus to the button that opened it, for example.
• Pressing Escape hides the tooltip while it is open.
• Hovering is delayed to prevent tooltips from flashing by when the pointer moves across the screen. The delays are static properties, so changing them applies to every tooltip in the application:

import { Tooltip } from '@sl-design-system/tooltip';

Tooltip.hoverShowDelay = 150; // default, in milliseconds
Tooltip.hoverHideDelay = 0; // default, in milliseconds

Showing and hiding programmatically

Set the open property to show or hide the tooltip regardless of its triggers. The tooltip is a popover, so you can also call showPopover() and hidePopover() on it directly.

To check whether a tooltip is showing, don't read the open property; use matches(':popover-open') instead. That also covers tooltips that were opened by one of the triggers.

const tooltip = document.querySelector('sl-tooltip');

tooltip.open = true;

if (tooltip.matches(':popover-open')) {
  // The tooltip is showing
}

Use disabled to stop a tooltip from showing altogether. A disabled tooltip hides itself if it is open, ignores its triggers and drops the ARIA relation with its anchors, so screen readers no longer announce it.

Positioning and size

The tooltip positions itself with CSS anchor positioning. It renders above the anchor by default, and flips to the other side when there is not enough room. Since this is plain CSS, you change the position by styling the tooltip:

sl-tooltip {
  /* Show the tooltip to the right of the anchor instead of above it */
  position-area: right;

  /* Prevent long tooltips from becoming too wide */
  max-inline-size: 200px;
}

Not every browser supports CSS anchor positioning yet. In those browsers you need the CSS Anchor Positioning polyfill, see add polyfills in the getting started guide.

The tooltip renders an invisible element between the anchor and the tooltip, so the pointer can travel from one to the other without the tooltip disappearing. It is available as the hover-bridge CSS part, which is handy when you want to see what it covers:

sl-tooltip::part(hover-bridge) {
  background: hotpink;
}

Migrating from older versions

The tooltip was rewritten to use the browser's popover and CSS anchor positioning APIs. If you are coming from an older version:

API

Tooltip component has a range of properties to define the experience in different use cases. The tooltip should be a sibling of the element it belongs to (not a child element) and is linked to that element with the for attribute.

Properties

Slots

CSS Parts

Accessibility considerations

Discoverability and readability

Ensure that tooltips are discoverable and readable using various input methods, including: Mouse or other pointer devices, keyboard navigation, screen readers, zoom software or any other assistive technology. Users with different abilities should be able to access tooltip content seamlessly.

For keyboard users to be able to see the tooltip it is important to use the tooltip only on elements that can get focus; for example a button or link. If the part of the interface you want to describe can not have the focus you can add a button with an information icon that will trigger the tooltip

Informative but non-essential content

Tooltips should provide information that enhances the user’s understanding of the UI but is not strictly necessary for operating it. Avoid critical information in tooltips, as users relying solely on assistive technologies may miss it.

Non-blocking behavior

When a tooltip is open, it should not obstruct the user from performing other tasks on the screen. Test this behavior across all responsive breakpoints to ensure consistent behavior regardless of screen size.

Keyboard interactions

Here's an overview of the common keyboard interactions associated with a tooltip:

WAI-ARIA

In the component itself we use multiple aria-attributes to assure the component works well with a range of assistive technologies. For some attributes however it is not possible for the Design System to add a meaningful value, because it relies on the context or way a component is used.

Attributes that we recommend you add in certain scenarios are mentioned below.

A tooltip is linked to the element it belongs to by either an aria-labelledby or an aria-describedby relation. The choice between the two depends on the context and the relationship between the tooltip and the anchor element. A good example of when to use aria-labelledby is when the tooltip provides a label or title for the anchor element, such as an icon only button (so button with only an icon) and no visible text. In this case, the tooltip serves as the accessible name for the button.

You can read more on the difference between the two attributes in the MDN article about aria-describedby

You do not set these attributes yourself. Point the tooltip at its anchor with the for attribute and pick the relation with type; the tooltip then takes care of the rest, for every element listed in for:

The tooltip sets up this relation using element references (ariaLabelledByElements and ariaDescribedByElements) rather than by writing an aria-labelledby or aria-describedby attribute on the anchor. Assistive technology sees the same thing, but you won't find the attribute on the anchor element when you inspect it in the browser.

Because the relation only exists while the tooltip is enabled, a disabled tooltip is not announced at all. Make sure an anchor that relies on the tooltip for its accessible name has another name when you disable the tooltip.