# Tooltip

A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.

Tabs: [Guidelines](/components/web/tooltip/tooltip.guidelines.md) · [Code](/components/web/tooltip/tooltip.code.md)

## 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](/patterns/overlays/overlays.about) 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.

```jsx
<Tooltip
    // What the tooltip renders
    content="Notifications"
    // What the screen reader announces
    aria-label="3 Notifications"
>
    <NakedButton>
        <Bell mr={8} /> 3
    </NakedButton>
</Tooltip>
```

```jsx
<Button tooltipProps={{content: 'Notifications', 'aria-label': '3 Notifications'}}>
    <Bell mr={8} /> 3
</Button>
```

### Displaying tooltips for disabled buttons

> If you are using our Button component, you can see more about disabled states and tooltips [here](/components/web/button/button.guidelines#disabled)

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`.

```jsx
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.

```jsx
<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](https://www.w3.org/TR/wai-aria-practices-1.2/#tooltip). See [Radix documentation](https://www.radix-ui.com/docs/primitives/components/tooltip#accessibility) for details.

## Related components

- [Help popover](/components/web/help-popover/help-popover.guidelines): An icon button with a question mark that reveals help information on click or tap.
- [Icon button](/components/web/icon-button/icon-button.guidelines): Enables users to control the visibility of other UI elements.
- [Popover](/components/web/popover/popover.guidelines): A small overlay that opens on demand. Popovers allow users to access additional content and actions without cluttering the page.