
Non-Disruptive Tooltips with HTML popover hint Semantics
Since the baseline arrival of the HTML Popover API, developers gained declarative top-layer rendering, built-in Escape handling, and light-dismiss behavior via popover="auto". Yet using popover="auto" for lightweight tooltips immediately exposed a subtle layering conflict: opening any auto popover automatically closes every other open auto popover outside its ancestor chain. If a user opens a toolbar dropdown menu (popover="auto") and then hovers over an icon button inside or beside it to inspect a tooltip, showing that tooltip as popover="auto" dismisses the active menu right under their cursor. Conversely, switching tooltips to popover="manual" preserves the underlying menu, but strips away automatic light-dismissal and forces teams back into writing global Escape listeners and focus-tracking boilerplate.
The HTML popover="hint" state resolves this exact clash by introducing a dedicated ephemeral tier in the top-layer popover stack. Showing a hint popover closes any other currently open hint popovers so only one tooltip appears at a time, while leaving unrelated auto popovers—such as open menus, comboboxes, or non-modal drawers—completely undisturbed. At the same time, hint popovers remain integrated into the browser's light-dismiss lifecycle: opening a new auto popover, pressing Escape, or clicking outside clears the active hint cleanly. Paired with CSS Anchor Positioning (anchor-name and position-anchor) and accessible aria-describedby associations, popover="hint" enables clean, non-disruptive tooltips with minimal JavaScript.
Example
<div class="toolbar">
<button
type="button"
popovertarget="format-menu"
aria-haspopup="menu"
>
Format
</button>
<div id="format-menu" popover="auto" role="menu">
<button
type="button"
role="menuitem"
aria-describedby="bold-tip"
data-tooltip="bold-tip"
>
Bold
</button>
</div>
</div>
<!-- Opening #bold-tip does NOT close #format-menu -->
<div id="bold-tip" popover="hint" role="tooltip">
Toggle bold text (Ctrl+B)
</div>
Implementation
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Non-Disruptive Popover Hint Tooltips</title>
<style>
:root {
--surface: #ffffff;
--border: #d4d4d8;
--ink: #18181b;
--tip-bg: #18181b;
--tip-ink: #fafafa;
}
.toolbar {
display: inline-flex;
gap: 0.5rem;
padding: 0.5rem;
border: 1px solid var(--border);
border-radius: 0.5rem;
background: var(--surface);
}
.tool-btn {
padding: 0.45rem 0.75rem;
border: 1px solid var(--border);
border-radius: 0.375rem;
background: var(--surface);
color: var(--ink);
font: inherit;
cursor: pointer;
}
.tool-btn:focus-visible {
outline: 2px solid #2563eb;
outline-offset: 2px;
}
[popover="auto"] {
margin: 0.35rem 0 0;
padding: 0.35rem;
border: 1px solid var(--border);
border-radius: 0.5rem;
background: var(--surface);
box-shadow: 0 10px 25px rgb(0 0 0 / 0.1);
}
.tooltip-hint {
position: fixed;
inset: auto;
margin: 0;
padding: 0.375rem 0.625rem;
border: 0;
border-radius: 0.375rem;
background: var(--tip-bg);
color: var(--tip-ink);
font-size: 0.8125rem;
line-height: 1.3;
pointer-events: none;
opacity: 0;
transform: translateY(4px);
transition:
opacity 140ms ease,
transform 140ms ease,
display 140ms allow-discrete,
overlay 140ms allow-discrete;
}
.tooltip-hint:popover-open {
opacity: 1;
transform: translateY(0);
}
@starting-style {
.tooltip-hint:popover-open {
opacity: 0;
transform: translateY(4px);
}
}
@supports (anchor-name: --a) and (position-area: top) {
.tooltip-hint {
position-area: top center;
margin-bottom: 0.5rem;
position-try-fallbacks: flip-block, flip-inline;
}
}
@media (prefers-reduced-motion: reduce) {
.tooltip-hint {
transition: none;
}
}
</style>
</head>
<body>
<div class="toolbar" role="toolbar" aria-label="Document actions">
<button
id="btn-save"
class="tool-btn"
type="button"
aria-describedby="tip-save"
data-tooltip="tip-save"
style="anchor-name: --anchor-save;"
>
Save
</button>
<button
id="btn-menu"
class="tool-btn"
type="button"
popovertarget="more-menu"
aria-haspopup="menu"
aria-describedby="tip-menu"
data-tooltip="tip-menu"
style="anchor-name: --anchor-menu;"
>
More
</button>
</div>
<div id="more-menu" popover="auto" role="menu">
<button
class="tool-btn"
type="button"
role="menuitem"
aria-describedby="tip-export"
data-tooltip="tip-export"
style="anchor-name: --anchor-export;"
>
Export Markdown
</button>
</div>
<div id="tip-save" class="tooltip-hint" popover="hint" role="tooltip" style="position-anchor: --anchor-save;">
Save draft to local storage
</div>
<div id="tip-menu" class="tooltip-hint" popover="hint" role="tooltip" style="position-anchor: --anchor-menu;">
Open additional document actions
</div>
<div id="tip-export" class="tooltip-hint" popover="hint" role="tooltip" style="position-anchor: --anchor-export;">
Download clean .md source file
</div>
<script>
const supportsHintPopover = (() => {
const probe = document.createElement('div');
probe.setAttribute('popover', 'hint');
return probe.popover === 'hint';
})();
const triggers = document.querySelectorAll('[data-tooltip]');
for (const trigger of triggers) {
const tipId = trigger.dataset.tooltip;
const tip = document.getElementById(tipId);
if (!tip) continue;
// Progressive fallback for browsers without native popover="hint"
if (!supportsHintPopover) {
tip.setAttribute('popover', 'manual');
}
let showTimer = null;
const positionFallback = () => {
if (CSS.supports('position-area: top')) return;
const rect = trigger.getBoundingClientRect();
tip.style.left = `${Math.max(8, rect.left)}px`;
tip.style.top = `${Math.max(8, rect.top - tip.offsetHeight - 8)}px`;
};
const openTip = () => {
clearTimeout(showTimer);
showTimer = setTimeout(() => {
if (!tip.matches(':popover-open')) {
tip.showPopover({ source: trigger });
positionFallback();
}
}, 120);
};
const closeTip = () => {
clearTimeout(showTimer);
if (tip.matches(':popover-open')) {
tip.hidePopover();
}
};
trigger.addEventListener('pointerenter', (event) => {
if (event.pointerType !== 'touch') openTip();
});
trigger.addEventListener('pointerleave', closeTip);
trigger.addEventListener('focusin', openTip);
trigger.addEventListener('focusout', closeTip);
trigger.addEventListener('keydown', (event) => {
if (event.key === 'Escape') closeTip();
});
}
</script>
</body>
</html>
Main Point: Using popover="hint" isolates lightweight tooltips into their own ephemeral top-layer tier so hovering or focusing controls never dismisses active auto menus or dialogs while still preserving native Escape and light-dismiss behavior.
Credits
Photo by Johannes Plenio on Unsplash