The Popover API provides developers with a standard, consistent, flexible mechanism for displaying popover content on top of other page content. Popover content can be controlled either declaratively using HTML attributes, or via JavaScript.
The Popover API provides developers with a standard, consistent, flexible mechanism for displaying popover content on top of other page content. Popover content can be controlled either declaratively using HTML attributes, or via JavaScript.
A very common pattern on the web is to show content over the top of other content, drawing the user's attention to specific important information or actions that need to be taken. This content can take several different names — overlays, popups, popovers, dialogs, etc. We will refer to them as popovers through the documentation. Generally speaking, these can be:
Popovers which are created using the popover API are always non-modal. If you want to create a modal popover, a <dialog>
element is the right way to go, although bear in mind that <dialog>
elements are not put in the top layer by default — popovers are. There is significant overlap between the two — you might for example want to create a popover that persists, but control it using declarative HTML. You can even turn a <dialog>
element into a popover if you want to combine popover control and top level placement with dialog semantics.
Typical use cases for the popover API include user-interactive elements like action menus, custom "toast" notifications, form element suggestions, content pickers, or teaching UI.
You can create popovers in two different ways:
html
<button popovertarget="mypopover">Toggle the popover</button> <div id="mypopover" popover>Popover content</div>
HTMLElement.togglePopover()
can be used to toggle a popover between shown and hidden.There are also new events to react to a popover being toggled, and CSS features to aid in styling popovers. All the new features are listed below.
See Using the popover API for a detailed guide to using this API.
popover
A global attribute that turns an element into a popover element; takes a popover state ("auto"
or "manual"
) as its value.
popovertarget
Turns a <button>
or <input>
element into a popover control button; takes the ID of the popover element to control as its value.
popovertargetaction
Specifies the action to be performed ("hide"
, "show"
, or "toggle"
) on the popover element being controlled by a control <button>
or <input>
.
::backdrop
The ::backdrop
pseudo-element is a full-screen element placed directly behind popover elements, allowing effects to be added to the page content behind the popover(s) if desired (for example blurring it out).
:popover-open
The :popover-open
pseudo-class matches a popover element only when it is in the showing state — it can be used to style popover elements when they are showing.
ToggleEvent
Represents an event notifying the user when a popover element's state toggles between showing and hidden. It is the event object for the beforetoggle
and toggle
events, which fire on popovers when their state changes.
HTMLElement.popover
Gets and sets an element's popover state via JavaScript ("auto"
or "manual"
), and can be used for feature detection. Reflects the value of the popover
global HTML attribute.
HTMLButtonElement.popoverTargetElement
and HTMLInputElement.popoverTargetElement
Gets and sets the popover element being controlled by the control button. The JavaScript equivalent of the popovertarget
HTML attribute.
HTMLButtonElement.popoverTargetAction
and HTMLInputElement.popoverTargetAction
Gets and sets the action to be performed ("hide"
, "show"
, or "toggle"
) on the popover element being controlled by the control button. Reflects the value of the popovertargetaction
HTML attribute.
HTMLElement.hidePopover()
Hides a popover element by removing it from the top layer and styling it with display: none
.
HTMLElement.showPopover()
Shows a popover element by adding it to the top layer.
HTMLElement.togglePopover()
Toggles a popover element between the showing and hidden states.
HTMLElement
beforetoggle
eventFired just before a popover element's state changes between showing and hidden, or vice versa.
HTMLElement
toggle
eventFired just after a popover element's state changes between showing and hidden, or vice versa. This event already existed to signal state changes on <details>
elements, and it seemed logical to extend it for popover elements.
See our Popover API examples landing page to access the full collection of MDN popover examples.
Specification |
---|
HTML Standard # dom-popover |
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
Popover_API |
114 | 114 | 114 | No | 100 | 17 | 114 | 114 | No | No | 17 | No |
© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Popover_API