Tooltip Documentation


The Tooltip component is a common element in the design system used to provide additional information or context to users when they interact with specific elements in a web app. Tooltips are typically triggered by hovering over or focusing on an element, and they appear as small floating boxes that display a brief message or explanation.

Anatomy of a Tooltip

A Tooltip consists of the following elements:

  1. Trigger Element: This is the element that users interact with to trigger the display of the Tooltip, such as a button, link, or icon.
  2. Tooltip Content: This is the actual content of the Tooltip, which provides additional information or context to the user. The content can include text, icons, or other visual elements.
  3. Arrow: The Tooltip may include an arrow pointing towards the trigger element, indicating the association between the trigger and the Tooltip.

How to Use

To use the Tooltip component, follow these guidelines:

  1. Identify the element that requires additional information or context for users.
  2. Add the necessary code and attributes to the trigger element to enable the Tooltip functionality. This may involve adding a data-tooltip attribute or using specific CSS classes.
  3. Provide appropriate content for the Tooltip that is concise, clear, and relevant to the trigger element.
  4. Ensure that the Tooltip is visually distinct from the surrounding elements and clearly associated with the trigger element.
  5. Test the Tooltip on different devices and screen sizes to ensure it functions correctly and is accessible.

When Not to Use

While the Tooltip component is a useful tool for providing additional information, there are situations where it may not be appropriate to use:

  1. Complex Information: If the content you need to display is too long or complex for a Tooltip, consider using a different component, such as a modal or a separate page.
  2. Critical Information: If the information is critical for users to understand or make decisions, it is better to provide it directly on the page rather than relying on a Tooltip.
  3. Mobile Devices: Tooltips that rely on hover interactions may not work well on touch devices. Consider alternative ways to provide the same information on mobile devices.

Differences from Disclosure (Show/Hide) Pattern

The Tooltip component differs from the Disclosure (Show/Hide) pattern in the following ways:

  1. Trigger Mechanism: Tooltips are triggered by hovering over or focusing on an element, while the Disclosure pattern typically involves clicking or tapping on a trigger element.
  2. Content Length: Tooltips are designed to display concise and brief information, while the Disclosure pattern allows for more extensive content to be shown or hidden.
  3. Visibility: Tooltips are typically displayed as small floating boxes that appear near the trigger element, while the Disclosure pattern reveals or hides content within the same page or container.

Accessibility Guidelines

To ensure the Tooltip component complies with level AA of WCAG 2.2, follow these accessibility guidelines:

  1. Keyboard Accessibility: Ensure that users can trigger the Tooltip using keyboard navigation by adding appropriate keyboard event handlers.
  2. Focus Management: When a Tooltip is triggered, ensure that the focus is correctly managed between the trigger element and the Tooltip, allowing users to navigate and interact with the content using the keyboard.
  3. Text Alternatives: Provide descriptive and meaningful aria-label or aria-describedby attributes for the trigger element to describe the Tooltip’s purpose and content.
  4. Color Contrast: Ensure that the color contrast between the Tooltip and its surrounding elements meets the WCAG 2.2 AA standards to ensure readability for users with visual impairments.
  5. Responsive Design: Test the Tooltip on different screen sizes and ensure that it remains accessible and usable on mobile devices.

Best Practices

When using the Tooltip component, consider the following best practices:

  1. Keep Content Concise: Keep the content of the Tooltip brief and focused on providing additional context or information. Long paragraphs or complex information may overwhelm users.
  2. Avoid Overlapping Tooltips: If multiple tooltips are used on a page, ensure that they do not overlap or obstruct each other, causing confusion for users.
  3. Provide Visual Cues: Use visual cues, such as arrows or icons, to indicate the association between the trigger element and the Tooltip.
  4. Test for Accessibility: Regularly test the Tooltip component for accessibility using screen readers, keyboard navigation, and assistive technologies to ensure it is usable for all users.
  5. Consider Mobile Usability: Take into account the limitations of hover interactions on touch devices and provide alternative ways to access the information provided by the Tooltip.

By following these guidelines and best practices, designers can effectively use the Tooltip component in the web app’s design to enhance user experience and provide valuable information to users.