Tooltips and pop-ups on public pages: ADA

Three rules for pop-up content

When pointer hover or keyboard focus makes extra content appear and later disappear, three things must be true. The content must be dismissible without moving the pointer or focus, hoverable so the pointer can travel onto it without it vanishing, and persistent, staying until the trigger is removed, the user dismisses it, or its information is no longer valid.

Two exceptions are worth knowing. Content drawn by the browser from an attribute such as title is the browser's job, not yours, as long as you have not restyled it. And the dismissible rule does not apply when the content communicates an input error or does not cover or replace other content.

Think of a screen magnifier user. At 400 percent, a tooltip may sit partly off screen; to read it they must move the pointer onto it. If it disappears as soon as the pointer leaves the icon, it can never be read.

Where public sites use hover content

Hover content on government sites tends to be help icons beside fee fields, library catalog preview cards, map pin details and navigation flyouts. Each is a small convenience that becomes a barrier when it cannot be reached with a keyboard, when it covers the label of the next field, or when it vanishes before a magnifier user has read it.

The fix is rarely complicated. Most failures come from building the pop-up on CSS :hover alone and never thinking about focus, Escape or the gap between trigger and content.

CSS-only tooltips that miss focus and Escape

A pseudo-element tooltip built from a data- attribute appears on hover only, cannot be reached by keyboard, and has no way to close.

<span class="tip" data-tip="Fees are due at filing">?</span>

.tip:hover::after { content: attr(data-tip); position: absolute; }

<button type="button" class="tip" aria-describedby="fee-tip">?
  <span class="visually-hidden">Filing fee help</span></button>
<div id="fee-tip" role="tooltip" hidden>Fees are due at filing.</div>

<script>
  const btn = document.querySelector(".tip");
  const tip = document.getElementById("fee-tip");
  let timer;
  const show = () => { clearTimeout(timer); tip.hidden = false; };
  const hide = () => tip.hidden = true;
  const hideSoon = () => { timer = setTimeout(hide, 200); };
  btn.addEventListener("focus", show);
  btn.addEventListener("blur", hide);
  btn.addEventListener("mouseenter", show);
  btn.addEventListener("mouseleave", hideSoon);
  tip.addEventListener("mouseenter", show);
  tip.addEventListener("mouseleave", hideSoon);
  document.addEventListener("keydown", e => { if (e.key === "Escape") hide(); });
</script>

Preview cards that vanish in transit

A catalog preview card that hides the instant the pointer leaves the title cannot be reached. A short grace period lets the pointer travel in, and entering the card cancels the hide.

title.addEventListener("mouseleave", () => card.hidden = true);

let timer;
const open  = () => { clearTimeout(timer); card.hidden = false; };
const close = () => { timer = setTimeout(() => card.hidden = true, 200); };
title.addEventListener("mouseenter", open);
title.addEventListener("focus", open);
title.addEventListener("blur", close);
title.addEventListener("mouseleave", close);
card.addEventListener("mouseenter", open);
card.addEventListener("mouseleave", close);
document.addEventListener("keydown", e => { if (e.key === "Escape") card.hidden = true; });

Hints that cover the next field

A hint that appears on focus and sits on top of the next label hides what the user needs to read, and the only way to dismiss it is to leave the field. Keep it in the flow so nothing is covered.

.parcel-hint {
  position: absolute;
  top: 100%;
  background: #fff;
  box-shadow: 0 2px 8px rgba(0,0,0,.3);
}
input:focus + .parcel-hint { display: block; }

.parcel-hint { display: none; margin-top: 0.25rem; }
input:focus + .parcel-hint { display: block; }
/* in the flow: the next field moves down instead of being covered */

Hover in native apps

On touch-first screens there is no hover, so the criterion mostly does not come into play. Where an app is used with a mouse or trackpad, for example on a tablet with a pointer, prefer the platform's own tooltip and help components over a custom overlay, and keep any overlay you build dismissible, hoverable and persistent.

Verifying the fix

1. Hover over each trigger. Move the pointer slowly onto the new content. It should stay.
2. Press Escape while the content is showing. It should close without the pointer or focus moving.
3. Tab to the trigger. The same content should appear, and Escape should close it.
4. Wait. The content must not disappear on a timer while the trigger is still hovered or focused.
5. At 400 percent zoom, check that a pop-up does not cover the control or label that you need to use next.

Common mistakes and a ship-it list

• Building a tooltip with :hover only and no focus handling.
• Hiding on mouseleave of the trigger without considering the content.
• Auto-hiding after a few seconds.
• Restyling a native title tooltip with a script and losing the exception.
• A flyout menu that closes if the pointer drifts diagonally.

Ship it when:

• Every hover or focus pop-up can be closed with Escape.
• The pointer can move onto the pop-up without it disappearing.
• It stays visible until hover or focus ends, or the user dismisses it.
• The pop-up is reachable by keyboard, and does not hide other content you need.

Keyboard access itself is a separate criterion, and the hover rules sit on top of it. For overlays built by a vendor, see vendors and third-party content.

Sources

• Understanding SC 1.4.13: Content on Hover or Focus (W3C), opens in a new tab
• 28 CFR Part 35, Subpart H: Accessibility of Web Information and Services (eCFR), opens in a new tab

Standard version: WCAG 2.1 (W3C Recommendation, 5 June 2018), as named in the Title II web rule. This page is for informational purposes only and is not legal advice. For binding requirements, refer to the official ADA statute and regulations, and ask a lawyer how they apply to you.