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.

<button popovertarget="my-popover">Open Popover</button>

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

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

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

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

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);
});

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:

<div popover>
  Parent
  <div popover>Child</div>
</div>

Place the controller inside the popover element:

<div popover>
  Parent
  <button popovertarget="foo">Click me</button>
</div>

<div popover id="foo">Child</div>

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.

<button popovertarget="my-popover"> 打开弹窗 </button>

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

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;
  }
}

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.

function supportsPopover() {
  return HTMLElement.prototype.hasOwnProperty('popover');
}