HTMLCSSLatest Web FeaturesUX

The Popover API: A Practical Guide

The Popover API brings native tooltips, dropdowns, and floating UIs to HTML. Learn how to build real UI patterns with popover, popovertarget, and anchor positioning.

U

UIXplor Team

July 10, 2026 · 9 min read

✦

01The Problem Popovers Solve

Tooltips, dropdowns, command palettes, date pickers, color pickers — all of them involve content that floats above the rest of the UI. Before the Popover API, every one of these required:

• JavaScript event listeners for open/close • Manual focus management and Escape handling • z-index stacking contexts (and the bugs they cause) • ARIA attributes wired up by hand • Click-outside detection logic

The Popover API collapses all of this into a few HTML attributes, handled natively by the browser.

02Core Anatomy of a Popover

A popover requires two things: a trigger and a target.

html
<!-- Trigger -->
<button popovertarget="my-popover">Open</button>

<!-- Target -->
<div id="my-popover" popover>
  I am floating content.
</div>

That's it. The browser wires up the button click to show/hide `#my-popover`. The element renders in the top layer — a special CSS stacking context above everything else, including elements with `z-index: 9999`.

The `popover` attribute defaults to `popover="auto"`, which means: • Clicking outside closes the popover (light dismiss) • Opening a new auto-popover closes previous ones • The Escape key closes it • Focus stays inside (for manual popovers)

03Auto vs Manual Popovers

html
<!-- Auto: closes on outside click, one open at a time -->
<div id="dropdown" popover="auto">...</div>

<!-- Manual: only closes when explicitly told to -->
<div id="notification" popover="manual">...</div>

Use `auto` for: dropdowns, tooltips, command palettes. Use `manual` for: toast notifications, non-blocking banners, tutorials that persist across clicks.

04Styling Popovers

Popovers have a default UA stylesheet that gives them position, padding, and a border. Override freely:

css
/* Target when open */
[popover] {
  border: none;
  padding: 0;
  border-radius: 12px;
  background: #1a1a2e;
  color: white;
  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
}

/* The backdrop behind auto popovers */
[popover]::backdrop {
  background: rgba(0, 0, 0, 0.3);
  backdrop-filter: blur(4px);
}

/* Animate in/out using @starting-style */
[popover] {
  transition: opacity 0.2s, transform 0.2s;
  transform: translateY(4px);
  opacity: 0;
}

[popover]:popover-open {
  opacity: 1;
  transform: translateY(0);
}

@starting-style {
  [popover]:popover-open {
    opacity: 0;
    transform: translateY(4px);
  }
}

The `@starting-style` rule is the key to entry animations. It defines the initial state *before* the popover's first render, allowing CSS transitions on `display: none → block` elements.

05JavaScript Control

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

// Open
popover.showPopover();

// Close
popover.hidePopover();

// Toggle
popover.togglePopover();

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

06Real Pattern: Dropdown Menu

html
<button popovertarget="nav-dropdown">Account ▾</button>

<nav id="nav-dropdown" popover>
  <a href="/profile">Profile</a>
  <a href="/settings">Settings</a>
  <a href="/logout">Log out</a>
</nav>
css
#nav-dropdown {
  padding: 8px;
  border-radius: 10px;
  background: #111;
  border: 1px solid rgba(255,255,255,0.1);
  min-width: 180px;
  display: flex;
  flex-direction: column;
  gap: 4px;
}

#nav-dropdown a {
  padding: 8px 12px;
  border-radius: 6px;
  color: rgba(255,255,255,0.7);
  text-decoration: none;
}

#nav-dropdown a:hover {
  background: rgba(255,255,255,0.08);
  color: white;
}

No JavaScript needed for the open/close behavior. The browser handles light-dismiss, Escape, and accessibility attributes.

07Browser Compatibility

The Popover API reached Baseline Newly Available in April 2024.

• Chrome 114+ ✅ • Firefox 125+ ✅ • Safari 17+ ✅ • Edge 114+ ✅

For older browsers, the API gracefully degrades — popovers will be visible in the DOM but won't have top-layer placement. Use a polyfill (`@oddbird/popover-polyfill`) for full coverage.

08FAQ

Can I position popovers relative to their trigger? Yes, with the CSS Anchor Positioning API (`anchor-name`, `position-anchor`). This is a companion feature that lets you position a popover relative to any element. Browser support is Chrome 125+ at the time of writing.

Does the Popover API replace the dialog element? No. `<dialog>` is for modal interactions that require user response before continuing. Popovers are for non-blocking, supplementary content.

Does it work with Shadow DOM? Yes. The top layer is document-level, so popovers from inside shadow roots still render above all other content.

Related UI Components

◈

Collections

All UI component collections

⚡

Micro Interactions

Ripple, tilt, glow interactions

Back to Blog