The Popover API: Overlays Without A JavaScript Library

The popover attribute (shorthand for popover="auto") can be added to essentially any element — a <div>, a <ul>, a <form> — hiding it by default via a browser-applied display: none equivalent, and rendering it on the top layer, the same stacking context <dialog> uses, once shown. This means a popover always renders above regular document content regardless of z-index, without the developer managing a portal or manual stacking context.

Unlike <dialog>, a popover never draws a backdrop and never makes the rest of the page inert — it's designed for overlays that coexist with an interactive page underneath, exactly the behavior a dropdown menu or tooltip needs but a blocking modal doesn't.

popovertarget="menu" on a <button> links it to the popover with a matching id, and by default toggles it: showing it if hidden, hiding it if currently shown. popovertargetaction="show" or "hide" pins a button to one direction only, useful when "open" and "close" are two visually distinct controls (an open button plus an in-panel close button) rather than a single toggle.

This mechanism replaces what used to require addEventListener("click", ...) plus manual open/closed state tracking with pure HTML — the browser owns the shown/hidden state, eliminating an entire category of state-desync bugs where JS and the DOM disagree about whether a menu is open.

popover="auto" (the default) enables light-dismiss: clicking outside the popover or pressing Escape closes it automatically, and opening a new auto popover closes any other currently-open auto popover — exactly the behavior expected of a dropdown menu, combobox listbox, or command palette. popover="manual" disables all of that: the popover only opens or closes via an explicit showPopover()/hidePopover()/togglePopover() call or a popovertargetaction-pinned button.

Choosing correctly matters for real UX: a toast notification using auto would vanish the instant a user clicked anywhere else on the page, defeating its purpose — manual, paired with a setTimeout to auto-hide after a few seconds, is the correct mode for that pattern.

The :popover-open pseudo-class matches a popover only while it's actually shown, the correct hook for entrance/exit transitions — combined with @starting-style and transition-behavior: allow-discrete the same way as an animating <dialog>, since a hidden popover is also fully removed from rendering via display: none.

CSS anchor positioning solves the previously JS-library-dependent problem of placing a popover relative to its trigger: anchor-name on the trigger element gives it a named anchor reference, and position-anchor plus anchor() functions on the popover position it relative to that anchor's edges — automatically repositioning on scroll and resize with zero JavaScript, directly replacing what libraries like Popper.js were built to solve.

Menus, Toasts, And Tooltips — Declared, Not Scripted. Dropdown menus, toast notifications, and tooltips all share the same underlying need: render above everything else, and dismiss on outside click or Escape. The Popover API gives every element that behavior via two HTML attributes, no JavaScript required.

popover Turns Any Element Into A Top-Layer Overlay. Adding the popover attribute (popover="auto" is the default when just popover is written) to any element hides it by default and, once shown, renders it on the same top layer <dialog> uses — above the rest of the page, with automatic light-dismiss behavior.

The popover Attribute. What does adding a bare popover attribute to an element do?

• →Hides it by default; when shown, it renders on the top layer with light-dismiss behavior
• →Only applies default popover CSS styling, with no behavior change
• →Immediately shows the element; JS is required to hide it

popovertarget + popovertargetaction: Zero-JS Triggers. A <button popovertarget="menu"> declaratively wires itself as that popover's trigger, toggling it open/closed by default; popovertargetaction="show" or "hide" pins the button to only one direction, useful when open and close are separate controls.

Declarative Popover Triggers. What does <button popovertarget="menu"> do by default, with no popovertargetaction specified?

• →Toggles the referenced popover open and closed on each click
• →Only ever shows the popover, never hides it
• →Nothing — popovertargetaction is required for any behavior

Light Dismiss: Automatic For popover="auto", Manual With popover="manual". popover="auto" (the default) closes automatically on an outside click or Escape, and closes any other open auto popover when a new one opens — the correct behavior for menus and comboboxes. popover="manual" opts out entirely, requiring explicit show/hide/toggle calls — appropriate for a toast notification that shouldn't disappear just because the user clicked elsewhere.

Choosing auto vs manual. A toast notification should remain visible for a few seconds regardless of what the user clicks elsewhere on the page. Which popover mode fits?

• →popover="auto"
• →popover="manual"
• →Neither mode supports this; a custom overlay is required

:popover-open Styles The Visible State. The :popover-open pseudo-class matches a popover element while it's actually showing, the natural hook for entrance/exit CSS transitions — paired with @starting-style the same way as a <dialog>, since a hidden popover is also removed from rendering entirely.

:popover-open Pseudo-Class. When does the :popover-open pseudo-class match a popover element?

• →While the popover is actually being shown
• →Always, regardless of visibility
• →Only while the mouse hovers over it

CSS Anchor Positioning Ties A Popover To Its Trigger. CSS anchor positioning lets a popover position itself relative to the element that triggered it — anchor-name on the trigger, position-anchor plus anchor() functions on the popover — solving tooltip/menu placement natively, without a JS positioning library recalculating on every scroll and resize.

CSS Anchor Positioning. What problem does CSS anchor positioning solve for popovers like menus and tooltips?

• →Positioning the popover relative to its trigger element, natively, without a JS library recalculating on scroll/resize
• →Applying color themes to popovers based on trigger state
• →It's unrelated to popovers entirely

Popover API Mastered. You now know how to build menus, toasts, and tooltips using the popover attribute and popovertarget triggers, choose between auto and manual dismissal modes, animate them with :popover-open, and position them natively with CSS anchor positioning.

Build A Native Popover. The Popover API links a trigger button to a popover element via popovertarget.