Building Native Popovers with the Popover API

JavaScript developers, take heed! The era of hand-rolling modal dialogs, tooltips, and menus with endless boilerplate is coming to a close. The Popover API provides a declarative way to create overlay UIs with built-in top-layer rendering, light-dismiss behavior, and accessibility, all from a single HTML attribute.

Saying Goodbye to Modal Boilerplate:

Historically, building a popover required a stack of concerns: z-index management, focus trapping, click-outside-to-close handlers, and backdrop elements. Libraries like Headless UI and Radix Popover abstracted this, but the underlying complexity remained. The Popover API bakes these behaviors into the browser itself.

Getting Started with the Popover API:

To utilize the Popover API, you need to ensure your target browsers support it. As of 2025, the API is supported across all major browsers including Chrome, Edge, Safari, and Firefox.

Here's a simple code snippet demonstrating how to use the API:

<!-- A button that triggers the popover -->
<button popovertarget="my-popover">Open Popover</button>

<!-- The popover element -->
<div id="my-popover" popover>
  <h2>Hello from the popover!</h2>
  <p>This content lives in the top layer and supports light dismiss.</p>
</div>

This markup creates a button that toggles the popover. The popover attribute opts the element into the API, and popovertarget wires the button to the popover without a single line of JavaScript.

Link to section: Manual Control with JavaScriptManual Control with JavaScript

When you need programmatic control, the API exposes methods on the element:

const popover = document.getElementById('my-popover');

// Show the popover
popover.showPopover();

// Hide the popover
popover.hidePopover();

// Toggle the popover
popover.togglePopover();

// Listen for state changes
popover.addEventListener('toggle', (event) => {
  if (event.newState === 'open') {
    console.log('Popover opened');
  } else if (event.newState === 'closed') {
    console.log('Popover closed');
  }
});

Link to section: Popover vs. Modal: Choosing the Right ModePopover vs. Modal: Choosing the Right Mode

The popover attribute accepts two values:

<!-- Auto popover: light dismiss enabled (default) -->
<div id="menu" popover="auto">...</div>

<!-- Manual popover: no light dismiss, explicit control -->
<div id="modal" popover="manual">...</div>

Use auto for menus, tooltips, and non-blocking overlays. Use manual when you need to force user interaction, like a confirmation dialog.

Embrace a New Era of Overlays:

The Popover API marks a significant advancement for web developers, dramatically reducing the code required to build common overlay patterns. With its declarative syntax and built-in behaviors, this API is set to revolutionize how we build interactive UI layers.

MDN Web Docs: Popover API

Start exploring the potential of the Popover API and eliminate modal boilerplate from your applications!