How to Build Accessible Tooltips with the Native Popover API

Introduction

For years, building a tooltip meant reaching for a JavaScript library. You would wire up hover events, manage focus states, and manually sync ARIA attributes—all while battling flickers, overlapping content, and broken keyboard navigation. The code grew fragile, and each new tooltip inherited that complexity. The Popover API changes this by giving browsers a native way to show and hide overlay content. It handles keyboard behavior, focus management, and accessibility out of the box. In this guide, you will learn how to replace your old tooltip logic with the Popover API, step by step.

What You Need

• A modern browser that supports the Popover API (Chrome 114+, Firefox 125+, Edge 114+, Safari 17.4+).
• A text editor (VS Code, Sublime, or any code editor).
• Basic knowledge of HTML, CSS, and a little JavaScript (optional).
• No JavaScript libraries required.

Step-by-Step Instructions

Step 1: Create the HTML Structure

Start with two elements: a trigger (like a button) and the tooltip content. Give the tooltip a unique id and add the popover attribute. This tells the browser the element is a popover.

<button class="info" popovertarget="my-tooltip">?</button>
<div id="my-tooltip" popover>Helpful text goes here</div>

The popovertarget attribute on the button connects it to the popover. Clicking the button will toggle the tooltip. By default, the popover is hidden.

Step 2: Connect the Trigger with popovertarget

For a tooltip that appears on hover or focus (not click), you need a bit more control. Instead of using popovertarget directly with a click, we will use a bit of JavaScript to handle hover/focus events. However, the Popover API also works with showPopover() and hidePopover() methods. For this guide, we will keep it simple and use the click toggle, then enhance with hover later.

If you want a pure HTML approach, use popovertargetaction="show" on the trigger for mouseenter and a separate trigger for hide. But a more robust method is to use JavaScript, which we cover in Step 6.

Step 3: Style the Tooltip with CSS

The Popover API uses the ::backdrop pseudo-element for the overlay, but for tooltips you usually do not need a backdrop. Use CSS to position the tooltip relative to its trigger. Keep it hidden until opened.

[popover] {
  position: absolute;
  inset: unset;
  top: calc(anchor(top) + 10px);
  left: anchor(left);
  margin: 0;
  padding: 0.5rem 1rem;
  background: #333;
  color: white;
  border: none;
  border-radius: 4px;
  font-size: 0.875rem;
  box-shadow: 0 2px 6px rgba(0,0,0,0.3);
  /* Popover API handles visibility; you only need to style the container */
}

Use CSS anchor positioning to place the tooltip relative to the trigger. This is still experimental but offers precise placement.

Step 4: Add ARIA Attributes for Accessibility

Even though the Popover API manages some ARIA properties, you should explicitly add role="tooltip" and link the trigger to the tooltip with aria-describedby.

<button class="info" popovertarget="my-tooltip" aria-describedby="my-tooltip">?</button>
<div id="my-tooltip" popover role="tooltip">Helpful text</div>

This ensures screen readers announce the tooltip content when the button receives focus.

Step 5: Handle Keyboard and Focus

One major advantage of the Popover API is that pressing Esc automatically hides the popover and returns focus to the trigger. No extra JavaScript needed. For tooltips that appear on hover, you must also show them on focus (for keyboard users). Use CSS :focus-visible or JavaScript to trigger showPopover() on focus and hidePopover() on blur.

Step 6: Add JavaScript for Hover and Focus (Optional but Recommended)

To make the tooltip appear on hover and focus, use simple JavaScript event listeners. This keeps the behavior predictable for all users.

const trigger = document.querySelector('.info');
const tooltip = document.getElementById('my-tooltip');

function showTooltip() {
  tooltip.showPopover();
}

function hideTooltip() {
  tooltip.hidePopover();
}

trigger.addEventListener('mouseenter', showTooltip);
trigger.addEventListener('mouseleave', hideTooltip);
trigger.addEventListener('focus', showTooltip);
trigger.addEventListener('blur', hideTooltip);

// Also hide if user clicks outside (Popover API does this automatically with light dismiss)

The Popover API handles light dismiss (clicking outside) by default, so you do not need extra code for that.

Step 7: Test Across Devices and Assistive Technology

Test with keyboard only (Tab, Esc, Enter). Test with a screen reader (VoiceOver, NVDA). Make sure the tooltip does not obstruct content on small screens. You can use CSS media queries or anchor positioning with anchor-scroll to adjust.

Tips for Success

• Use popover with manual state for tooltips: The default auto state allows only one open popover and closes on Esc. For tooltips that should stay open until the user moves away, use popover="manual" and control visibility via JavaScript.
• Check browser support: The Popover API is widely supported, but some features like CSS anchor positioning are still in flux. Always check Can I Use for the latest status.
• Progressive enhancement: Provide fallback content for older browsers. The popover attribute is ignored in unsupported browsers, so the tooltip will be visible by default. Wrap the tooltip in a container and hide it with a no-js class if needed.
• Keep tooltips short: Avoid overwhelming users. Tooltips are for brief explanations, not long paragraphs. Use simple, concise text.
• Avoid nesting popovers: Do not place a popover inside another popover; it can confuse screen readers and focus management.

With the Popover API, you now have a robust, lightweight way to build tooltips that work for everyone—without the baggage of a library. Start using it today and simplify your UI code.