Skip to content
Telescope
Components

Tooltip

A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.
(Psst...hover this button to see the tooltip in action)

Features

  • Opens when the trigger is focused or hovered.
  • Closes when the trigger is activated or when pressing escape.

When to use

See our design pattern around overlays to learn why and when you should use this component.

Examples

Using the aria-label prop

In rare cases the trigger might contain information that is relevant to the user, like a badge showing the count for notifications. In these cases we want the screen reader user to know both the content in the tooltip, but also the content in the badge. For screen reader users, the only content announced to them is whatever is in the tooltip. For these cases, use the aria-label prop.

Show code
<Tooltip
    // What the tooltip renders
    content="Notifications"
    // What the screen reader announces
    aria-label="3 Notifications"
>
    <NakedButton>
        <Bell mr={8} /> 3
    </NakedButton>
</Tooltip>
Show code
<Button tooltipProps={{content: 'Notifications', 'aria-label': '3 Notifications'}}>
    <Bell mr={8} /> 3
</Button>

Displaying tooltips for disabled buttons

Information:

If you are using our Button component, you can see more about disabled states and tooltips here

Disabled buttons do not fire events, so to display a tooltip in this case, you'll have to:

  • Render the Trigger as span or div.
  • Ensure the button has no pointerEvents.
const StyledButton = styled(Button)`
    pointer-events: none;
`


<Tooltip content="Good job!">
    {/* tabIndex={0} makes the element focusable */}
    <div tabIndex={0}>
        <StyledButton disabled>…</StyledButton>
    </div>
</Tooltip>

Changing the position or alignment of the tooltip

Use these options if the tooltip would otherwise overlay important information. For consistency, the default positioning of top should be preferred and center in the case of the alignment.

Show code
<Tooltip content="Notifications" side="bottom" align="start">
    <NakedButton>
        <Bell mr={8} /> 3
    </NakedButton>
</Tooltip>

Best practices

Do
Use tooltips to explain what happens when an interactive element is activated.
Don't
Use tooltips to describe non-interactive elements. It will not be accessible for keyboard or screen reader users.
Do
Use tooltips to provide brief information about an interactive element.
Don't
Place lengthy text or complex content in tooltips. They're meant for quick insights.
Do
Use tooltips to provide supplementary information about an interactive element.
Don't
Use tooltips to communicate crucial information related to task completion.
Do
Show text only within the tooltip content.
Don't
Include links or other interactive elements within the tooltip content.

Accessibility

Adheres to the WAI-ARIA practices for tooltips. See Radix documentation for details.

Related components

  • Help popover: An icon button with a question mark that reveals help information on click or tap.
  • Icon button: Enables users to control the visibility of other UI elements.
  • Popover: A small overlay that opens on demand. Popovers allow users to access additional content and actions without cluttering the page.
Didn't find what you were looking for?
Let us know in #team-design-systems or make a request.
Edit this page