Mastering the New HTML Popover API: From Basics to Advanced Animations

Introduction

When we talk about popovers, many people think of modal dialogs, which are a common UI pattern. The new Popover API lets you implement popovers—including toast‑style components—more elegantly, handling z‑index conflicts and focus management automatically.

Top‑layer display – Popovers appear on the page’s top layer, eliminating the need for manual z‑index adjustments.

Lightweight dismiss – Clicking outside the popover closes it and returns focus.

Default focus management – Only one popover can be open at a time; opening a new one closes the previous.

Keyboard accessibility – Pressing Esc or toggling twice closes the popover and restores focus.

Accessible component binding – Semantic connections between the popover element and its trigger.

Quick Start

You can create a popover using only HTML: a button with

popovertarget

and a target element with

popover

and a unique

id

.

Set the

popover

attribute on the element that should act as the popover.

Give the popover element a unique

id

.

Set the button’s

popovertarget

to that

id

to link them.

<code>&lt;button popovertarget="my-popover"&gt;Open Popover&lt;/button&gt;

&lt;div id="my-popover" popover&gt;
  &lt;p&gt;I am a popover with more information. Hit &lt;kbd&gt;esc&lt;/kbd&gt; or click away to close me.&lt;/p&gt;
&lt;/div&gt;</code>

The trigger can also use

popovertargetaction

with values

hide

,

show

, or

toggle

.

popovertargetaction : hide | show | toggle

To make an element a popover, add the

popover

attribute with values

auto

(default) or

manual

. In

auto

mode clicking outside closes the popover; in

manual

it does not. Adding an

overlay

can affect event propagation.

Because popovers are rendered as top‑layer elements, their stacking cannot be altered with

z-index

, potentially removing the need for React portals.

Imperative Control

Even without JavaScript you can use the Popover API, but it also provides methods and events for programmatic control, such as

showPopover

,

hidePopover

, and

togglePopover

, as well as

beforetoggle

and

toggle

events.

showPopover

hidePopover

togglePopover

beforetoggle

toggle

<code>&lt;div class="action"&gt;
  &lt;button data-acion="hide"&gt;关闭modal&lt;/button&gt;
  &lt;button data-acion="show"&gt;显示modal&lt;/button&gt;
  &lt;button data-acion="toggle"&gt;切换modal&lt;/button&gt;
&lt;/div&gt;

&lt;div class="modal" id="my-popover" popover&gt;
  &lt;button popovertargetaction="hide" popovertarget="my-popover"&gt;关闭&lt;/button&gt;
  &lt;div&gt;这里是一个正经弹窗&lt;/div&gt;
&lt;/div&gt;</code>

<code>const modal = document.querySelector('.modal');
const actions = document.querySelector('.action');

actions.addEventListener('click', (e) => {
  switch (e.target.dataset.acion) {
    case 'hide':
      modal.hidePopover();
      break;
    case 'show':
      modal.showPopover();
      break;
    case 'toggle':
      modal.togglePopover();
      break;
    default:
      break;
  }
});

modal.addEventListener('beforetoggle', function (e) {
  console.log('beforetoggle', e);
});

modal.addEventListener('toggle', function (e) {
  console.log('toggle', e);
});</code>

Nested Popover

By default only one popover can be open at a time, but you can nest popovers to create dialog‑within‑dialog or cascading menus. Three approaches are possible.

Direct DOM nesting:

<code>&lt;div popover&gt;
  Parent
  &lt;div popover&gt;Child&lt;/div&gt;
&lt;/div&gt;</code>

Place the controller inside the popover element:

<code>&lt;div popover&gt;
  Parent
  &lt;button popovertarget="foo"&gt;Click me&lt;/button&gt;
&lt;/div&gt;

&lt;div popover id="foo"&gt;Child&lt;/div&gt;</code>

Animating Popover

Adding animation gives popovers a sense of life. Since the popover’s

display

changes from

none

to

block

automatically, we can use CSS discrete property transitions to animate the change.

<code>&lt;button popovertarget="my-popover"&gt; 打开弹窗 &lt;/button&gt;

&lt;div id="my-popover" popover&gt;
  模态弹窗会打断用户的正常操作，要求用户必须对其进行回应，否则不能继续其它操作；
&lt;/div&gt;</code>

<code>button {
  font-size: 100%;
  padding: 0.75rem;
  background: white;
  transition-duration: 0.5s;
  border: 4px solid plum;
  background: lavenderblush;
  border-radius: 1rem;
}

[popover] {
  background: black;
  color: white;
  font-weight: 400;
  padding: 1rem 1.5rem;
  border-radius: 1rem;
  max-width: 20ch;
  line-height: 1.4;
  top: 2rem;
  margin: 0 auto;
}

body {
  background: #fcf9fb;
  display: grid;
  font-size: 1.5rem;
  font-family: system-ui, sans-serif;
  place-items: center;
  height: 100dvh;
}

/* Show animation */
[popover]:popover-open {
  translate: 0 0;
}

/* Hide animation */
[popover] {
  transition: translate 0.7s ease-out, display 0.7s ease-out allow-discrete;
  translate: 0 -22rem;
}

@starting-style {
  [popover]:popover-open {
    translate: 0 -22rem;
  }
}
</code>

The

allow-discrete

property enables animation when the element switches from

display:none

to

block

. Removing it shows the difference.

Compatibility

The Popover API is supported by the latest versions of the three major browsers. For production use, perform a feature‑detection check before relying on it.

<code>function supportsPopover() {
  return HTMLElement.prototype.hasOwnProperty('popover');
}</code>