Verify content on hover or focus
Description
This rule does not automatically validate anything. It simply reminds you to manually verify that additional content that appears on hover or focus (such as tooltips, popovers, or dropdown menus) meets the three requirements of WCAG 2.2 Success Criterion 1.4.13 Content on Hover or Focus (Level AA): dismissible (the user can close the content without moving the pointer or focus), hoverable (the pointer can be moved over the additional content without it disappearing), and persistent (the content stays visible until the trigger is removed or the user dismisses it). The rule scans for elements with a title attribute, elements with the class .tooltip, and elements with the class .dropdown, and reports a reminder to manually inspect each instance. No automated pass/fail determination is made.
Additional content triggered solely by hover or focus can create significant barriers for users with motor disabilities, screen reader users, and individuals with low vision. For example, a tooltip that vanishes the instant the pointer moves slightly can make it impossible for users with tremors to read the content. Similarly, a dropdown that closes when focus moves to the next item prevents keyboard-only users from making a selection. SC 1.4.13 ensures that such content is robust enough to be usable by everyone.
Disabilities impacted
- Visual impairments – Users with low vision who rely on screen magnification may need to move the magnified viewport to read tooltip content. If the tooltip disappears when the pointer moves even slightly (e.g., to scroll the magnified area), the user cannot access the information. Similarly, screen reader users may never hear
titleattribute content because many screen readers do not announcetitleby default – the content may be entirely invisible to assistive technology. - Motor disabilities – Individuals with tremors, reduced fine motor control, or who use switch devices, eye-tracking, or speech-recognition software have difficulty keeping a pointer or focus stationary. A tooltip that disappears when the cursor moves a few pixels or when focus shifts between elements effectively denies access to the information. The
hoverable
requirement is especially critical for this group because it allows them to move the cursor onto the tooltip content itself without it vanishing. - Cognitive disabilities – People with attention deficits, memory impairments, or processing difficulties benefit from persistent, predictable content. A tooltip that appears and disappears rapidly can be distracting and disorienting, causing the user to lose their train of thought or miss critical instructions. The persistent requirement of SC 1.4.13 helps ensure users have adequate time to read and understand the content before it disappears.
Why it matters
Content that appears on hover or focus is widespread across modern web interfaces: tooltips on icon-only buttons, dropdown navigation menus, date-picker popups, and help-text flyouts are common examples. When these patterns fail the dismissible, hoverable, or persistent requirements, they exclude users who cannot interact with a mouse or who rely on keyboard navigation. The ADA, the European Accessibility Act (EAA), and Section 508 of the Rehabilitation Act all require that digital content be perceivable and operable for people with disabilities. Beyond compliance, hover-and-focus content failures are a common source of user frustration and task abandonment, even for non-disabled users on touch devices where hover does not exist. Ensuring that all additional content is dismissible, hoverable, and persistent creates a more robust and inclusive experience for every user, on every device.
Coding problems and solutions
Common coding problems
Since this rule is a manual-only reminder with no automated element validation, the following checklist describes what a human reviewer should manually verify when auditing for content-on-hover-or-focus compliance:
- Tooltip disappears when pointer moves off the trigger – A tooltip that is shown via
:hoverormouseenter/mouseleaveand vanishes when the cursor leaves the trigger element violates the hoverable requirement. The reviewer must check that the pointer can move from the trigger onto the tooltip content without it closing. - No dismiss mechanism for hover-triggered content – If additional content appears on hover, the user must be able to dismiss it without moving the pointer. The most common approach is pressing the Escape key. A reviewer must test that every hover-triggered overlay, tooltip, or popup can be closed via keyboard.
- Dropdown or popup closes when focus leaves the trigger – Keyboard users navigate with the Tab key. If a dropdown menu closes the moment focus moves to the first menu item, the user cannot interact with it. The reviewer must verify that focus can move into the additional content and that it remains open while any part of it is focused.
- Content disappears after a fixed timeout – Some implementations auto-hide tooltip content after a few seconds even when the pointer or focus remains on the trigger. This violates the persistent requirement. The reviewer must verify that content remains visible as long as the trigger is hovered or focused (or until the user explicitly dismisses it).
- Using only the
titleattribute for critical information – Thetitleattribute is not a reliable way to provide hover content because it cannot be dismissed, is not hoverable, is not keyboard accessible (it only appears on hover, not focus), and has inconsistent screen reader support. The reviewer must check that any information conveyed viatitleis also available through an accessible alternative. - Touch devices have no hover – Content that only appears on hover is completely inaccessible on touch devices. The reviewer must verify that hover-only patterns are supplemented with tap-to-toggle or persistent alternatives for touch users.
How to fix it
Use a dismissible, hoverable, and persistent tooltip pattern with ARIA
When implementing custom tooltips or popovers, use ARIA roles such as role="tooltip" and the aria-describedby relationship to associate the additional content with its trigger. Ensure the tooltip can be dismissed via the Escape key, that the pointer can move from the trigger into the tooltip, and that the tooltip remains visible until explicitly dismissed or the trigger loses hover and focus.
<button type="button" id="help-btn"
aria-describedby="help-tooltip">
Save
</button>
<div id="help-tooltip" role="tooltip"
class="tooltip" hidden>
Saves your current progress to the server.
Press Escape to close this tip.
</div>
<script>
const btn = document.getElementById('help-btn');
const tip = document.getElementById('help-tooltip');
const showTooltip = () => {
tip.hidden = false;
};
const hideTooltip = () => {
tip.hidden = true;
};
btn.addEventListener('mouseenter', showTooltip);
btn.addEventListener('mouseleave', () => {
// Do not hide if pointer is over the tooltip
globalThis.setTimeout(() => {
if (!tip.matches(':hover')) {
hideTooltip();
}
}, 200);
});
btn.addEventListener('focus', showTooltip);
btn.addEventListener('blur', (e) => {
// Keep open if related target is inside the tooltip
if (tip.contains(e.relatedTarget)) {
return;
}
hideTooltip();
});
tip.addEventListener('mouseleave', hideTooltip);
tip.addEventListener('keydown', (e) => {
if (e.key === 'Escape') {
hideTooltip();
btn.focus();
}
});
</script><!-- Tooltip via title attribute: not dismissible,
not hoverable, not keyboard accessible -->
<button title="Saves your current progress to the server.">
Save
</button>
<!-- CSS-only tooltip that vanishes on mouseleave -->
<style>
.tip-trigger .tooltip-content { display: none; }
.tip-trigger:hover .tooltip-content { display: block; }
</style>
<span class="tip-trigger">
Save
<span class="tooltip-content">Saves your progress.</span>
</span>Make dropdown menus keyboard accessible with hover + focus support
Dropdown navigation menus are a common source of SC 1.4.13 failures. The menu must remain open when the pointer moves from the top-level item into the dropdown, and keyboard users must be able to tab into the dropdown and navigate its items without the menu closing. Use aria-expanded to communicate the open/closed state and manage visibility with both :hover and :focus-within.
<nav aria-label="Main navigation">
<ul>
<li class="dropdown"
aria-expanded="false">
<button type="button" id="products-btn"
aria-haspopup="true"
aria-controls="products-menu">
Products
</button>
<ul id="products-menu" role="menu" hidden>
<li role="none">
<a role="menuitem" href="/software">Software</a>
</li>
<li role="none">
<a role="menuitem" href="/hardware">Hardware</a>
</li>
<li role="none">
<a role="menuitem" href="/services">Services</a>
</li>
</ul>
</li>
</ul>
</nav>
<script>
const dropdown = document.querySelector('.dropdown');
const btn = document.getElementById('products-btn');
const menu = document.getElementById('products-menu');
const openMenu = () => {
menu.hidden = false;
dropdown.setAttribute('aria-expanded', 'true');
};
const closeMenu = () => {
menu.hidden = true;
dropdown.setAttribute('aria-expanded', 'false');
};
btn.addEventListener('mouseenter', openMenu);
dropdown.addEventListener('mouseleave', closeMenu);
btn.addEventListener('focus', openMenu);
btn.addEventListener('keydown', (e) => {
if (e.key === 'ArrowDown' || e.key === 'Enter') {
openMenu();
const first = menu.querySelector('a');
if (first) {
first.focus();
e.preventDefault();
}
}
});
menu.addEventListener('keydown', (e) => {
if (e.key === 'Escape') {
closeMenu();
btn.focus();
}
});
// Keep open while any descendant is focused
dropdown.addEventListener('focusout', (e) => {
if (dropdown.contains(e.relatedTarget)) {
return;
}
closeMenu();
});
</script><!-- CSS-only dropdown that closes on mouseleave -->
<style>
.dropdown-menu { display: none; }
.dropdown:hover .dropdown-menu { display: block; }
</style>
<nav>
<ul>
<li class="dropdown">
<a href="#">Products</a>
<ul class="dropdown-menu">
<li><a href="/software">Software</a></li>
<li><a href="/hardware">Hardware</a></li>
</ul>
</li>
</ul>
</nav>
<!-- Keyboard users cannot open or interact with this menu -->Use JavaScript for dismissible hover content with Escape key support
Any content shown on hover must provide a keyboard-accessible dismiss mechanism. The most universal approach is listening for the Escape key on the overlay content itself. Always return focus to the triggering element after dismissal so keyboard users can continue navigating from where they left off.
<label for="email">Email:</label>
<input type="email" id="email"
aria-describedby="email-hint">
<div id="email-hint" role="tooltip"
class="tooltip" hidden>
Use your work email address.
Press Escape to close.
</div>
<script>
const input = document.getElementById('email');
const hint = document.getElementById('email-hint');
const showHint = () => { hint.hidden = false; };
const hideHint = () => {
hint.hidden = true;
input.focus();
};
input.addEventListener('mouseenter', showHint);
input.addEventListener('focus', showHint);
input.addEventListener('mouseleave', () => {
globalThis.setTimeout(() => {
if (document.activeElement !== input &&
!hint.matches(':hover')) {
hideHint();
}
}, 300);
});
input.addEventListener('blur', () => {
globalThis.setTimeout(() => {
if (document.activeElement !== hint &&
!hint.contains(document.activeElement)) {
hideHint();
}
}, 200);
});
hint.addEventListener('keydown', (e) => {
if (e.key === 'Escape') {
e.preventDefault();
hideHint();
}
});
hint.addEventListener('mouseleave', () => {
if (document.activeElement !== input) {
hideHint();
}
});
</script><!-- Tooltip only on hover, no dismiss, no keyboard access -->
<input type="email" id="email"
title="Use your work email address.">
<!-- Pure CSS tooltip that vanishes on mouseleave -->
<style>
input + .hint { display: none; }
input:hover + .hint { display: block; }
</style>
<input type="email" id="email2">
<span class="hint">Use your work email address.</span>Provide a persistent fallback for touch and keyboard users
Since hover does not exist on touch devices, and some users cannot use a mouse at all, hover-only content must be supplemented with an alternative mechanism. The most reliable approach is a toggle button or a small icon that reveals the same information on click or tap, ensuring parity across all input methods.
<label for="username">
Username
<button type="button" id="username-help"
aria-label="Help for username field"
aria-expanded="false"
aria-controls="username-hint">
<span aria-hidden="true">?</span>
</button>
</label>
<input type="text" id="username">
<div id="username-hint" role="tooltip" hidden>
Your username must be 6–20 characters,
letters and numbers only.
</div>
<script>
const helpBtn = document.getElementById('username-help');
const hint = document.getElementById('username-hint');
const toggleHint = () => {
const expanded = helpBtn.getAttribute('aria-expanded');
const isOpen = expanded === 'true';
hint.hidden = isOpen;
helpBtn.setAttribute('aria-expanded', String(!isOpen));
};
helpBtn.addEventListener('click', toggleHint);
helpBtn.addEventListener('keydown', (e) => {
if (e.key === 'Escape' && hint.hidden === false) {
hint.hidden = true;
helpBtn.setAttribute('aria-expanded', 'false');
helpBtn.focus();
}
});
// Also show on hover for mouse users
helpBtn.addEventListener('mouseenter', () => {
if (hint.hidden) {
toggleHint();
}
});
helpBtn.addEventListener('mouseleave', () => {
if (hint.hidden === false &&
document.activeElement !== helpBtn) {
toggleHint();
}
});
</script><!-- Hover-only tooltip: completely inaccessible on touch -->
<style>
.help-icon:hover + .help-text { display: block; }
.help-text { display: none; }
</style>
<span class="help-icon" tabindex="0">?</span>
<span class="help-text">Must be 6–20 characters.</span>
<!-- No aria attributes, no keyboard activation -->Add sufficient delay before showing and hiding tooltips
Rapid appearing and disappearing of additional content (sometimes called flickering tooltips
) causes problems for users with motor tremors and cognitive disabilities. Implement a small delay (e.g., 300 ms) on show and a short delay on hide to prevent transient pointer movements from toggling the content. This makes the interface more forgiving without noticeably affecting responsive users.
<button type="button" id="info-btn"
aria-describedby="info-tooltip">
More info
</button>
<div id="info-tooltip" role="tooltip" hidden>
Additional details about this feature.
</div>
<script>
const infoBtn = document.getElementById('info-btn');
const infoTip = document.getElementById('info-tooltip');
let showTimer = null;
let hideTimer = null;
const cancelTimers = () => {
if (showTimer !== null) {
globalThis.clearTimeout(showTimer);
showTimer = null;
}
if (hideTimer !== null) {
globalThis.clearTimeout(hideTimer);
hideTimer = null;
}
};
const showTooltip = () => {
cancelTimers();
showTimer = globalThis.setTimeout(() => {
infoTip.hidden = false;
showTimer = null;
}, 300);
};
const hideTooltip = () => {
cancelTimers();
hideTimer = globalThis.setTimeout(() => {
infoTip.hidden = true;
hideTimer = null;
}, 200);
};
infoBtn.addEventListener('mouseenter', showTooltip);
infoBtn.addEventListener('mouseleave', hideTooltip);
infoBtn.addEventListener('focus', showTooltip);
infoBtn.addEventListener('blur', (e) => {
if (infoTip.contains(e.relatedTarget)) {
return;
}
hideTooltip();
});
infoTip.addEventListener('mouseenter', () => {
if (hideTimer !== null) {
globalThis.clearTimeout(hideTimer);
hideTimer = null;
}
});
infoTip.addEventListener('mouseleave', hideTooltip);
infoTip.addEventListener('keydown', (e) => {
if (e.key === 'Escape') {
cancelTimers();
infoTip.hidden = true;
infoBtn.focus();
}
});
</script><!-- No delay: tooltip flickers on accidental pointer movement -->
<style>
.tip { display: none; }
.trigger:hover .tip { display: block; }
.trigger:hover { position: relative; }
</style>
<span class="trigger">
More info
<span class="tip">Additional details.</span>
</span>
<!--
Users with tremors may trigger tooltip on/off rapidly,
causing disorientation.
-->Known Limitations
- Manual-only verification – This rule performs no automated validation of hover or focus behavior. It cannot determine whether a tooltip is dismissible via the Escape key, whether the pointer can move into the additional content, or whether the content persists as required. It only reports a reminder whenever elements matching
[title],.tooltip, or.dropdownare present. The auditor must manually inspect every instance. - Single-page applications (SPAs) – Client-side rendering in frameworks like Angular, React, or Vue often dynamically creates and destroys tooltip and dropdown elements. The rule evaluates the DOM at the time of scanning; tooltips that are lazy-loaded or rendered only after user interaction may not be present and will not trigger the manual-check reminder.
- Shadow DOM – Elements with
title,.tooltip, or.dropdownthat are rendered inside shadow roots (e.g., inside custom Web Components) are not traversed by the rule’s selector, which operates on the light DOM only. Tooltips and dropdowns inside encapsulated components will not trigger the reminder and may go unaudited. - Third-party widgets and embeds – Tooltips, dropdowns, and hover content injected by third-party libraries, social media embeds, or advertising networks may be absent from the DOM at scan time or may be rendered inside iframes that the rule cannot inspect. These elements cannot be flagged automatically and require separate manual review.
- Dynamically bound JavaScript events – The rule has no visibility into JavaScript event listeners. A
<button>without atitleattribute or a.tooltipclass could still trigger hover content through an event handler bound in a separate script. The auditor must review all JavaScript code paths, not just DOM attributes. - CSS-only tooltips – Tooltips implemented entirely with CSS
:hoverpseudo-classes and adjacent sibling or descendant selectors do not use thetitleattribute or the.tooltipclass, so they may not be captured by the rule’s selector at all. These patterns are completely invisible to the rule and must be identified through manual code review or functional testing.
Resources
- WCAG 2.2 Success Criterion 1.4.13 Content on Hover or Focus – W3C
- Understanding SC 1.4.13 Content on Hover or Focus – W3C WAI
- Technique C38: Using CSS to avoid content-on-hover failures – W3C WAI
- Technique SCR39: Making content on hover or focus dismissible – W3C WAI
- ARIA
tooltiprole – MDN Web Docs - Failure F95: Content on hover not dismissible – W3C WAI
Rule
- Audit: accessibility
- Standard: WCAG
- Level: AA
- Success Criteria: 1.4.13
- Rule ID:
content-on-hover-focus