skip to content

Under WCAG 2.2 success criterion 1.4.13 Content on Hover or Focus, what must a custom tooltip do to conform?

level: middleimportance: must knowfreq 55%

answer

  1. three conditions, Level AA
  2. dismiss without moving anything
  3. the pointer can travel onto it
  4. no timer hides it
  5. focus must show it too

basics

~20 s

It must be dismissible without moving pointer or focus, hoverable so the pointer can move onto it without it vanishing, and persistent until the trigger is left, it is dismissed, or its information is no longer valid.

solid answer

~40 s

1.4.13 Content on Hover or Focus is a **Level AA** criterion with three conditions. **Dismissible**: a mechanism, usually Escape, closes the tooltip without moving the pointer or focus — unless it shows an input error or does not obscure or replace other content. **Hoverable**: if hover can open it, the pointer can move from the trigger onto the tooltip without it disappearing, which matters to magnifier users and anyone with a large pointer. **Persistent**: it stays until hover or focus leaves, the user dismisses it, or its information is no longer valid — never on a timer. The criterion exempts tooltips whose presentation is entirely the platform's own. Separately, content that opens on hover must also open on keyboard focus, which the understanding document ties to 2.1.1 Keyboard (Level A).

go deeper

for a junior

Recall the three words — dismissible, hoverable, persistent — and that the tooltip must also appear on keyboard focus.

for a middle

Explain each condition with the user it protects, the two dismissible exemptions, and the platform-controlled exception.

for a senior

Diagnose failing tooltips from a review or a magnifier session and turn the conditions into a manual test checklist for the component.

for a principal

Decide where the system enforces these behaviours, in one shared overlay primitive rather than per component, so every hover popup inherits them.

## What the criterion covers WCAG 2.2 success criterion **1.4.13 Content on Hover or Focus** (Level AA) applies whenever receiving and then removing pointer hover or keyboard focus makes **additional content** appear and then disappear. Custom tooltips, sub-menus and other non-modal popups that show on hover and focus are its main examples. Its purpose, in the words of its understanding document, is that users can perceive the additional content and dismiss it without disrupting their use of the page. It does **not** cover: - content whose visual presentation is controlled entirely by the platform, such as the built-in tooltip a platform draws from a native text alternative; - modal dialogs, which must take focus and so should not appear on hover or focus at all; - elements that are simply revealed on focus, such as a skip link, because they are not additional content. ## The three conditions | Condition | What it requires | Who it protects | |---|---|---| | **Dismissible** | A mechanism closes the content without moving pointer hover or keyboard focus — typically Escape. Exempt if the content shows an input error, or does not obscure or replace other content. | Screen-magnifier users whose small viewport is covered by the popup | | **Hoverable** | If hover can trigger it, the pointer can move over the content without it disappearing. | Magnifier users who pan onto the content; users with large pointers that hide text | | **Persistent** | Content stays visible until hover or focus is removed, the user dismisses it, or its information is no longer valid. | Anyone who needs more time to find and read the content | ## Hover and focus as triggers The understanding document adds that content which can be triggered by pointer hover **should also be triggerable by keyboard focus**, pointing to **2.1.1 Keyboard** (Level A). A tooltip specification in a design system therefore states both triggers: - **Focus** on the trigger shows the tooltip; focus leaving hides it. Focus never moves into the tooltip. - **Hover** on the trigger shows it after a short delay, and it stays while the pointer is over either the trigger or the tooltip. - **Escape** hides it while focus and pointer stay where they are. - A small **hide delay** — a grace period when the pointer leaves the trigger — lets the pointer cross the gap onto the tooltip without it vanishing. - A **show delay** is common practice so that sweeping the pointer across a toolbar does not flash every tooltip; the length is a convention chosen for feel, not a number any standard mandates. ## Example: a balance tooltip on a tablet A retail bank's app runs on a tablet with a keyboard case and a trackpad. Next to 'Available balance' sits an info icon with a custom tooltip: 'Includes your arranged overdraft.' Three defects surface in review: 1. The tooltip hides itself after three seconds even while the pointer rests on the icon — a **persistent** failure. 2. It sits a few pixels below the icon and closes the instant the pointer leaves the icon, so a user with a large pointer cannot move onto it to read the text hidden under the cursor — a **hoverable** failure. 3. It covers the transaction list below and only closes by moving away, which also moves a magnifier user's view — a **dismissible** failure. The fix: no timer; a hide grace period and a tooltip placed adjacent to its trigger; Escape to dismiss; and the same behaviour when the icon receives keyboard focus. ## Testing it 1. Hover the trigger, then move the pointer onto the tooltip: it must stay. 2. Rest the pointer on the trigger and wait: it must not disappear on its own. 3. With the tooltip open, press Escape without moving anything: it must close. 4. Tab to the trigger: the tooltip must appear; Tab away: it must disappear. 5. Repeat at high magnification, where most failures become obvious. Automated scanners rarely catch these behaviours, so they belong in the component's manual test checklist and in its interaction tests. ## Common mistakes - A tooltip that closes the moment the pointer leaves the trigger, with a gap the pointer cannot cross. - An auto-hide timer added to keep screens tidy. - Treating 'move the pointer away' as the dismiss mechanism. - A tooltip that opens on hover only and never on keyboard focus. Building the three conditions into one shared overlay primitive, rather than into each tooltip, means every hover or focus popup in the system inherits them.

  • Does 1.4.13 apply to a native platform's built-in tooltip that shows a control's name?
    Its exception covers additional content whose visual presentation is controlled by the platform and not modified by the author. A custom-drawn tooltip is covered; the platform's untouched built-in one is not, though the design system still decides whether relying on it is good enough.
  • Why is an inline validation message exempt from the dismissible condition?
    The criterion exempts additional content that communicates an input error, because such a message needs the user's attention and remedial action. Letting it be waved away without fixing the value would hide the very information the user needs.

saying these in an interview costs you the question

  • A tooltip may hide itself after a few seconds to keep the screen tidy.
  • Moving the pointer away counts as the dismiss mechanism 1.4.13 asks for.
  • Hover alone is enough as a trigger; keyboard users can read the label instead.
  • 1.4.13 is a Level AAA criterion, so most products can skip it.
  • Every popup on hover must be dismissible, even an input error message.