dev-skills

Appearance

Popover API for Overlays ​

For transient floating surfaces (capture popups, comment panels, toasts, fallback dialogs), reach for the native Popover API before hand-rolling an overlay with z-index management and global event listeners. In a modern-browser-only context it removes whole categories of bug.

When to use ​

Use the Popover API for any overlay that floats above the page and dismisses on its own terms: menus, panels, capture popups, toasts, and fallback dialogs. It fits anywhere you would otherwise stack a high z-index and wire up your own Escape and outside-click handling.

The pattern ​

Mark the element with the popover attribute and drive it from JavaScript with showPopover(), hidePopover(), and togglePopover():

html
<div class="panel" popover="auto">…</div>
<div class="toast" popover="manual" role="status" aria-live="polite"></div>
javascript
const panel = shadow.querySelector(".panel");

// open / close / toggle
panel.showPopover();
panel.hidePopover();
panel.togglePopover();
  • popover="auto" gives the platform's light-dismiss for free: Escape and an outside click both close it, and opening one auto popover closes others.
  • popover="manual" opens and closes only when you call the methods, which is right for toasts and panels that should not vanish on an outside click.

Top-layer paint replaces the z-index war ​

An open popover paints in the browser's top layer. It sits above all page content in DOM order, so it always renders on top without any z-index. Delete the 2147483600-style magic numbers from every surface that becomes a popover. Non-popover chrome anchored to content (a floating action button, selection chip, or margin pin) keeps its z-index, since it is not in the top layer.

Free light-dismiss replaces hand-rolled listeners ​

Because an auto popover is dismissed by the platform, the Escape branch in a keydown handler and the outside-click half of a global mousedown listener both disappear. The only cleanup left is your own state, which you can hang off the popover's toggle event:

javascript
pop.addEventListener("toggle", function (event) {
  if (event.newState === "closed") pending = null;
});

Guard show and hide ​

showPopover() throws if the element is already open, and hidePopover() throws if it is already closed. Guard every call so repeated triggers do not crash:

javascript
function openPopover(element) {
  if (!element.matches(":popover-open")) element.showPopover();
}

function closePopover(element) {
  if (element.matches(":popover-open")) element.hidePopover();
}

Animate with discrete transitions ​

A popover toggles display and the top-layer overlay property, both of which are discrete. To keep an exit animation, transition them with allow-discrete and set the entry state with @starting-style:

css
.toast {
  opacity: 0;
  transform: translateY(10px);
  transition:
    opacity 0.18s,
    transform 0.18s,
    overlay 0.18s allow-discrete,
    display 0.18s allow-discrete;
}

.toast:popover-open {
  opacity: 1;
  transform: translateY(0);
}

@starting-style {
  .toast:popover-open {
    opacity: 0;
    transform: translateY(10px);
  }
}

Trade-offs ​

  • Imperative vs declarative. The declarative popovertarget attribute needs an id on the target. If the component is deliberately id-free (to avoid colliding with host page ids), drive the popovers imperatively with showPopover() and friends instead, which keeps the API's benefits without reintroducing ids.
  • Coordinate space. Top-layer popovers are fixed to the viewport, so anchor them to a selection's viewport rect (no scrollX/scrollY offset). Content- anchored chrome that must scroll with the page stays position: absolute in document coordinates.
  • Browser support. The Popover API ships in Chrome 114+, Edge 114+, Firefox 125+, and Safari 17+. Use it when targeting modern browsers; for older targets fall back to a manually managed overlay.

See also ​