The Pop-Up API

The Pop-Up API provides a standard mechanism for displaying pop-ups on the Web.

Published on Updated on

The Pop-Up API provides developers with a standard, consistent, flexible mechanism for displaying pop-up content on top of other page content. Pop-ups can be light dismissed with a close signal. Close signals include closing by clicking out of the pop-up or pressing Esc, and opening other non-ancestral pop-ups. 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

Pop-ups are used constantly, all over the web. Developers keep having to reimplement pop-up 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 Pop-Up API.

Any HTML element can be turned into a pop-up using the popover attribute. The Pop-Up API provides the following default behavior:

  • Pop-ups are hidden by default (using display: none). To display a pop-up by default on page load, you can give it the defaultopen attribute.
  • Pop-ups are also given a default fixed position in the center of the viewport, padding, and a border.
  • When shown, pop-ups are promoted to the top layer (above document and outside of document flow).
  • Pop-ups have light dismiss. By that, we mean you can close the pop-up with a close signal, such as clicking outside the pop-up, keyboard-navigating to another element, or pressing the Esc key.
  • Popups are designed to be accessible, with an element defined as a pop-up trigger automatically getting aria-haspopup semantics. In addition, focus into the pop-up can be controlled using autofocus and, when the pop-up 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 pop-up. See Focus Management for more details.
  • Opening a pop-up dismisses other pop-ups that are not ancestral pop-ups.
Key Term

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

The popover attribute can take one of the following values:

  • auto: The pop-up exhibits the standard behavior explained above.
  • manual: Manual pop-ups 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 pop-ups.

You can show and dismiss pop-ups in two different ways:

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

HTML attributes

defaultopen
Causes a pop-up to automatically open on page load.
popover
Turns an element into a pop-up.
popovertoggletarget
Creates a trigger element that toggles an associated pop-up between shown and hidden states.
popovershowtarget
Creates a trigger element that shows an associated hidden pop-up.
popoverhidetarget
Creates a trigger element that dismisses an associated shown pop-up.

CSS features

::backdrop
Pseudo-element that sits behind an open pop-up 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 pop-up is open—for example you might want to blur or darken it.
:open
Pseudo-class allowing a pop-up to be styled, but only when it is being shown.

Interfaces

Extensions to Element

Properties:

defaultOpen
Causes a pop-up to automatically open on page load. DOM definition of the HTML defaultopen attribute.
popOver
Turns an element into a pop-up. DOM definition of the HTML popover attribute.
onpopovershow
Event handler property for the popovershow event, fired on the pop-up when it is shown.
onpopoverhide
Event handler property for the popoverhide event, fired on the pop-up when it is dismissed.

Instance methods:

showPopOver()
Shows a pop-up element.
hidePopOver()
Dismisses a pop-up element.

Events:

popovershow
Fired on the pop-up when it is shown.
popoverhide
Fired on the pop-up when it is dismissed.

Extensions to HTMLButtonElement and HTMLInputElement

Properties:

popOverToggleTarget
Creates a trigger element that toggles an associated pop-up between shown and hidden states. DOM definition of the HTML popovertoggletarget attribute.
popOverShowTarget
Creates a trigger element that shows an associated hidden pop-up. DOM definition of the HTML popovershowtarget attribute.
popOverHideTarget
Creates a trigger element that dismisses an associated shown pop-up. 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 pop-up. The first two are equivalent:

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

Specify that a pop-up should open automatically on page load with defaultopen:

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

Declaratively create buttons to show and hide the pop-up:

<button popovershowtarget="my-popup">Show pop-up</button>
<button popoverhidetarget="my-popup">Dismiss pop-up</button>

Declaratively create a single button to toggle the pop-up between shown and hidden states:

<button popovertoggletarget="my-popup">Show pop-up</button>

Use the :open pseudo-class to style the pop-up when it has been shown. The following example transitions the pop-up 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 pop-up 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 pop-ups:

  popup.showPopOver();
popup.hidePopOver();

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

  popup.addEventListener('popovershow', () => {
popupToggleBtn.textContent = 'Dismiss pop-up';
})

popup.addEventListener('popoverhide', () => {
popupToggleBtn.textContent = 'Show pop-up';
})

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.