# Accessible Tooltip: Hover, Focus and Escape

Source: https://allyway.ai/glossary/accessible-tooltip

An accessible tooltip is a small popup with extra information about an element that appears on mouse hover and on keyboard focus, is linked to its trigger with aria-describedby and meets WCAG 1.4.13 Content on Hover or Focus at Level AA: it can be dismissed, hovered and stays visible until the user moves away.

An accessible tooltip is a small text bubble that explains a control – "Copy link", "Required for invoices", a hint next to a form field – and that everyone can read and get rid of. Many tooltips only open on mouse hover, vanish the moment the pointer moves towards them, or cover the very text people are trying to read. For keyboard users, screen magnifier users and touchscreen users that means the hint is either unreachable or in the way.

## What it means

The visual rules come from [WCAG 1.4.13 Content on Hover or Focus](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html) (Level AA). Wherever hover or keyboard focus makes additional content appear, three conditions apply – explained in detail under [content on hover or focus](https://allyway.ai/glossary/content-on-hover-or-focus):

| Condition | What it requires |
|---|---|
| Dismissible | Users can close the tooltip without moving the pointer or focus, usually with Escape – unless it shows an input error or covers no other content |
| Hoverable | If hover opens it, the pointer can move onto the tooltip without it disappearing |
| Persistent | It stays visible until hover or focus leaves, the user dismisses it, or its information is no longer valid |

The exception: tooltips whose look is controlled by the browser and not changed by the author. That is why the native `title` attribute is not covered by 1.4.13 – but it shows only on mouse hover, not on keyboard focus or touch, so it is a poor place for important information.

For the code, the W3C [Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/) describes the basics (it is still marked as work in progress):

- the popup has `role="tooltip"`
- the trigger points to it with `aria-describedby`, so screen readers read it as a description
- focus stays on the trigger – a tooltip never receives focus itself
- Escape closes it

> **Note:** > **A tooltip is not a name**
> An icon button that only explains itself through a tooltip still needs an [accessible name](https://allyway.ai/glossary/accessible-name) of its own, for example an `aria-label`. The tooltip adds a description; it does not replace the label.

## Examples

```html title="Example"
<button type="button" aria-label="Copy link"
        aria-describedby="tip-copy">
  <svg aria-hidden="true" focusable="false">…</svg>
</button>
<div role="tooltip" id="tip-copy" hidden>
  Copies the address of this page to your clipboard
</div>
```

The script shows the tooltip on `mouseenter` and `focus`, keeps it open while the pointer is over the button or the tooltip, and hides it on `mouseleave`, `blur` and Escape. The [icon button](https://allyway.ai/glossary/icon-button) has its own name, so a screen reader announces "Copy link, button, Copies the address of this page to your clipboard".

**Do:** Do

Open the tooltip on hover and on keyboard focus, let Escape close it, keep it open while the pointer is on it, place it so it does not cover the trigger, and keep its text short.

**Don't:** Don't

Put essential instructions only in a tooltip, rely on the `title` attribute for keyboard or touch users, close it after a fixed timeout, add links or buttons inside it, or use a tooltip as the only name of an icon button.

For content with links or longer explanations, use a toggletip – a small button that opens the hint on click – or show the text directly on the page.

## How to check an accessible tooltip



## Questions

Q: How do you make a tooltip accessible?
A: Show it on hover and keyboard focus, link it with `aria-describedby`, give the popup `role="tooltip"`, close it with Escape and keep it open while the pointer is over it. Important information belongs on the page, not only in a tooltip.

Q: Is the title attribute accessible?
A: It is outside WCAG 1.4.13 because the browser controls how it looks. But it only appears on mouse hover, so keyboard and touch users usually never see it. Use it for nothing essential.

Q: Should a tooltip close on Escape?
A: Yes. WCAG 1.4.13 requires a way to dismiss the extra content without moving the pointer or focus, and the W3C tooltip pattern uses Escape for it.

Q: Can a tooltip contain links or buttons?
A: A tooltip never receives focus, so people could not reach interactive content in it. Use a toggletip or a non-modal dialog instead.

Q: How do tooltips work on mobile?
A: Touchscreens have no hover. Make sure the information is available another way – as visible text, or behind a button that opens it on tap.
