The Popover API

The Popover API provides a standard mechanism for displaying popovers on the Web.

Published on Updated on

The Popover API provides developers with a standard, consistent, flexible mechanism for displaying popover content on top of other page content. Popovers can be light dismissed with a close signal. Close signals include closing by clicking out of the popover or pressing Esc, and opening other non-ancestral popovers. Typical use cases include user-interactive elements like action menus, form element suggestions, content pickers, teaching UI, and the Listbox portion of a <select> control.

Current status

Concepts and usage

Popovers are used constantly, all over the web. Developers keep having to reimplement popover styling, positioning and z-index stacking, focus management, keyboard interactions, and accessibility semantics for each new project. As well as duplication of work, this has also resulted in an inconsistent end-user experience across different apps. In answer to this, the Open UI group published a proposal for the Popover API.

Any HTML element can be turned into a popover using the popover attribute. The Popover API provides the following default behavior:

  • Popovers are hidden by default (using display: none).
  • Popovers are also given a default fixed position in the center of the viewport, padding, and a border.
  • When shown, popovers are promoted to the top layer (above document and outside of document flow).
  • Popovers have light dismiss. By that, we mean you can close the popover with a close signal, such as clicking outside the popover, keyboard-navigating to another element, or pressing the Esc key.
  • Popovers are designed to be accessible, with an element defined as a popover trigger automatically getting aria-haspopup semantics. In addition, focus into the popover can be controlled using autofocus and, when the popover is light dismissed, a heuristic determines where focus should go next. For example, focus could go back to the previously-focused element, or an element clicked outside of the popover. See Focus Management for more details.
  • Opening a popover dismisses other popovers that are not ancestral popovers.
Key Term

A popover trigger is an element that causes a change in the state of the popover it is associated with, for example a <button> that shows and dismisses the popover.

The popover attribute can take one of the following values:

  • auto: The popover exhibits the standard behavior explained above.
  • manual: Manual popovers cannot be light dismissed (they can only be dismissed by an explicit trigger element or by JavaScript), and they don't automatically dismiss previously-shown popovers.

You can show and dismiss popovers in two different ways:

The Popover API also comes with a couple of handy CSS features, a ::backdrop pseudo-element to style the document behind the popover when it is shown (for example, you might want to blur or fade the page while showing popovers), and an :open pseudo-class to style the popover only when it is open.

HTML attributes

popover
Turns an element into a popover.
popovertoggletarget
Creates a trigger element that toggles an associated popover between shown and hidden states.
popovershowtarget
Creates a trigger element that shows an associated hidden popover.
popoverhidetarget
Creates a trigger element that dismisses an associated shown popover.

CSS features

::backdrop
Pseudo-element that sits behind an open popover in the stacking order, but in front of the rest of the document, and spans the entire width and height of the viewport. Allows the rest of the content to be styled while the popover is open—for example you might want to blur or darken it.
:open
Pseudo-class allowing a popover to be styled, but only when it is being shown.

Interfaces

Extensions to HTMLElement

Properties:

popover
Turns an element into a popover. DOM definition of the HTML popover attribute.
onpopovershow
Event handler property for the popovershow event, fired on the popover when it is shown.
onpopoverhide
Event handler property for the popoverhide event, fired on the popover when it is dismissed.

Instance methods:

showPopover()
Shows a popover element.
hidePopover()
Dismisses a popover element.

Events:

popovershow
Fired on the popover when it is shown.
popoverhide
Fired on the popover when it is dismissed.

Extensions to HTMLButtonElement and HTMLInputElement

Properties:

popoverToggleTarget
Creates a trigger element that toggles an associated popover between shown and hidden states. DOM definition of the HTML popovertoggletarget attribute.
popoverShowTarget
Creates a trigger element that shows an associated hidden popover. DOM definition of the HTML popovershowtarget attribute.
popoverHideTarget
Creates a trigger element that dismisses an associated shown popover. DOM definition of the HTML popoverhidetarget attribute.

Examples

This section shows basic usage of the API; for more substantial code including numerous complete examples, check out Pop-ups: They're making a resurgence! by Jhey Tompkins.

Declaratively create different types of popover. The first two are equivalent:

<p id="my-popover" popover>Hello!</p>
<p id="my-popover" popover="auto">Hello!</p>
<p id="my-popover" popover="manual">Hello!</p>

Declaratively create buttons to show and hide the popover:

<button popovershowtarget="my-popover">Show popover</button>
<button popoverhidetarget="my-popover">Dismiss popover</button>

Declaratively create a single button to toggle the popover between shown and hidden states:

<button popovertoggletarget="my-popover">Show popover</button>

Use the :open pseudo-class to style the popover when it has been shown. The following example transitions the popover in from the bottom of the viewport, rather than have it appear in the center:

p[popover] {
transform: translateY(60vh);
}

p[popover]:open {
transition: transform 0.6s;
transform: translateY(0vh);
}

Use the ::backdrop pseudo-element to style the document behind the popover while it is being shown. The following example darkens the rest of the content:

p[popover]::backdrop {
background-color: rgba(0,0,0,0.5);
}

Use JavaScript to programmatically show and hide popovers:

  popover.showPopover();
popover.hidePopover();

Use event listeners to respond to popovers being shown and hidden. The following example switches the textContent of the popover trigger button so that it makes sense when the popover is in its shown and hidden states:

  popover.addEventListener('popovershow', () => {
popoverToggleBtn.textContent = 'Dismiss popover';
})

popover.addEventListener('popoverhide', () => {
popoverToggleBtn.textContent = 'Show popover';
})

Feedback

Your feedback on the API is welcome. Send an email to the Open UI group, or go to their Getting Involved page to learn about other ways to ask questions and contribute.

See also

Updated on Improve article

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.