HTML Popover API

The HTML Popover API lets you display temporary content above the rest of a page without building positioning, stacking, focus-return, and dismissal behavior from scratch. It works well for action menus, teaching tips, status panels, and non-modal information.

A native popover differs from a dialog. It does not make the rest of the page inactive, so users can continue interacting with other content unless you intentionally create modal behavior with a dialog.

Create a Popover Without JavaScript

Add the popover attribute to the hidden element. Connect a button with popovertarget, whose value must match the popover element's ID.

Run this example:

<button popovertarget="course-info">View details</button>

<div id="course-info" popover>
  <h2>CSS Layout Course</h2>
  <p>Duration: 4 weeks</p>
  <button popovertarget="course-info"
          popovertargetaction="hide">Close</button>
</div>

The browser initially hides the popover. Activating the first button shows it in the top layer. The close button hides it through declarative HTML.

Choose a Popover State

The empty attribute popover means popover="auto". Auto is suitable for most menus and temporary information. Use manual for persistent panels that should not close after an outside click or Escape request.

Control the Target Action

A popover target button toggles by default. Set popovertargetaction to show, hide, or toggle when the intended action must be explicit.

<!-- These controls have one clear action each. -->
<button popovertarget="help" popovertargetaction="show">Open help</button>
<button popovertarget="help" popovertargetaction="hide">Close help</button>
<aside id="help" popover="manual">Keyboard shortcuts appear here.</aside>

Use the JavaScript Popover Methods

JavaScript can show, hide, or toggle a popover when the action depends on application logic. The element provides showPopover(), hidePopover(), and togglePopover().

const statusPanel = document.querySelector("#status-panel");

async function saveProfile() {
  // Save the profile before showing confirmation.
  await updateProfile();
  statusPanel.showPopover();
}

function closeStatus() {
  // Hide the currently displayed popover.
  statusPanel.hidePopover();
}

Calling a state-changing method when the element is not in a valid state can raise an exception. Keep the controls and current state predictable.

Respond to Popover Events

The beforetoggle event fires before the state changes and can be cancelled. The toggle event fires after the change. Their oldState and newState values are open or closed.

const menu = document.querySelector("#account-menu");

menu.addEventListener("toggle", (event) => {
  // Keep the trigger's state available to assistive technology.
  document.querySelector("#account-button").setAttribute(
    "aria-expanded",
    event.newState === "open"
  );
});

Style a Popover and Its Backdrop

Style the popover like any element. The ::backdrop pseudo-element can add a visual layer behind a displayed popover, but it does not make the popover modal.

[popover] {
  border: 0;
  border-radius: 10px;
  padding: 1.25rem;
  box-shadow: 0 10px 35px rgb(0 0 0 / 22%);
}

[popover]::backdrop {
  /* The page remains interactive for a non-modal popover. */
  background: rgb(15 23 42 / 18%);
}

Understand Light Dismiss and Focus

Auto and hint popovers support light dismiss: an outside pointer action or an appropriate close request, such as Escape, closes the topmost popover. The browser also places popovers in the top layer, so ordinary page stacking contexts do not cover them.

Use an actual button as the invoker. It provides keyboard activation and a clear accessible control. Give the popover a meaningful heading when it contains more than a short message, and test where focus moves when it opens and closes.

Do not use a popover for a task that must block the page until the user responds. Use the HTML dialog element with modal behavior for that requirement.

Popover Accessibility Guidelines

• Make every trigger understandable without relying only on an icon.
• Keep keyboard focus order logical and place interactive controls in meaningful source order.
• Do not show critical information only on pointer hover.
• Ensure text, controls, focus indicators, and backdrop styling have sufficient contrast.
• Test Escape, outside-click dismissal, zoom, and narrow screens.

Common Popover Mistakes

• Using a target value that does not match a unique element ID.
• Choosing manual state but providing no visible close control.
• Expecting ::backdrop to disable the underlying page.
• Using custom div elements instead of accessible buttons for invocation.
• Confusing the native HTML API with a Bootstrap popover component.

Conclusion

The HTML Popover API provides top-layer display, declarative controls, light dismissal, events, and JavaScript methods for temporary interface content. Choose auto, hint, or manual behavior carefully, keep controls accessible, and use a modal dialog when the surrounding page must become inactive.