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.

TooltipDirective API

When working on the application with LitElement, TooltipDirective can be used as an alternative way for adding sl-tooltip component. This is a LitElement specific directive - a custom LitElement directive. More information you can find here.

The TooltipDirective can be added to the anchor element e.g. button by passing a string for the tooltip content:

  ${tooltip('This tooltip is from a directive')}

The complete usage example might appear as follows:

  <sl-button ${tooltip('This tooltip is from a directive')}>I have a tooltip</sl-button>

Add config with the directive

You can also pass a second argument: a config object. Use this to control how the tooltip appears.

// Basic string content + position + max width
html`<sl-button ${tooltip('More info', { position: 'right', maxWidth: 240 })}>Hover me</sl-button>`;

// Use ariaRelation: 'label' when the tooltip should be used as the accessible label (e.g. icon only buttons)
html`<sl-button ${tooltip('Settings', { ariaRelation: 'label' })}><sl-icon name="smile"></sl-icon></sl-button>`;

Available config options

• position: Where the tooltip shows relative to the anchor. One of: top, right, bottom, left, top-start, top-end, right-start, right-end, bottom-start, bottom-end, left-start, left-end. Default: top.
• maxWidth: A number (pixels). The maximum width of the tooltip.
• ariaRelation: How the tooltip is linked for screen readers. A description (default) uses aria-describedby, label uses aria-labelledby and should be used when the tooltip text is the actual label of the anchor element (like an icon-only button).

If you omit a config it just uses its default behaviour. Config options are optional.

Tooltip.lazy helper

Tooltip.lazy is a small helper that creates a tooltip only when the user first hovers or focuses the target element. This avoids unnecessary processing if the user never interacts with it.

Basic shape:

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

const cleanup = Tooltip.lazy(targetElement, tooltip => {
  // Runs once when the tooltip is actually created
  tooltip.textContent = 'Hello there';
});

With options:

Tooltip.lazy(button, tooltip => {
    tooltip.textContent = 'Settings';
    tooltip.position = 'bottom-start';
  },
  {
    ariaRelation: 'label',
    context: shadowRoot,
    parentNode: someContainer,
  }
);

Available options

• ariaRelation: How the tooltip is linked for screen readers. A description (default) uses aria-describedby, label uses aria-labelledby and should be used when the tooltip text is the actual label of the anchor element (like an icon-only button).
• context: A Document or ShadowRoot to create the <sl-tooltip> element in. If not provided, the tooltip will be created on the target element if it has a shadowRoot, or the root node of the target element.
• parentNode: A Node where the tooltip element should be inserted. This can be useful when you don't want the tooltip to be added next to the anchor element. If not provided, it will be added next to the anchor element.

Tooltip API

Tooltip component has a range of properties to define the experience in different use cases. sl-tooltip component is recommended to use in all non-LitElement applications. Tooltip component should be a sibling of the element it is describing (not a child element).

Properties

Methods

Slots

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 meaningfull 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 can be linked to another element by either using aria-describedby or aria-labelledby attributes. 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