JavaScript Reference ยท DOM: Document and Elements
The Popover API
Reference for the Popover API: the popover attribute, popovertarget buttons, showPopover(), hidePopover(), togglePopover(), auto and manual modes and events.
The Popover API turns any element into a layer that floats above the page: menus, tooltips-with-content, notifications, pickers. Add the popover attribute and the browser hides the element until it is shown, puts it in the top layer (above everything, no z-index fights), and handles light dismiss (click outside or press Esc) and focus return.
You can open and close popovers with no script at all, using a button's popovertarget attribute, or from JavaScript with showPopover(), hidePopover() and togglePopover().
<button popovertarget="menu">Menu</button> <div id="menu" popover>Menu content</div>
menu.showPopover();
Try it
Syntax
<element popover> <!-- auto (default) --> <element popover="manual"> <button popovertarget="id" popovertargetaction="show|hide|toggle">
element.showPopover() element.hidePopover() element.togglePopover() element.togglePopover(force)
Parameters
| Name | Description |
|---|---|
popover |
Empty or "auto": light dismiss, and opening one closes other auto popovers (except ancestors). "manual": no light dismiss, no closing of others. |
popovertarget |
On a <button> or <input type="button">: the id of the popover it controls. |
popovertargetaction |
"toggle" (default), "show" or "hide". |
force |
Optional boolean for togglePopover(): true forces open, false forces closed. |
Return value
showPopover() and hidePopover() return undefined. togglePopover() returns true if the popover is open afterwards, false if not.
Events and CSS
beforetoggle (cancelable when opening) and toggle fire on the popover; the event has oldState and newState ("open" or "closed"). The CSS :popover-open pseudo-class matches an open popover and ::backdrop styles its backdrop.
Exceptions
Calling showPopover() on an element without the popover attribute, or on a disconnected element, throws an error (NotSupportedError or InvalidStateError).
Usage notes
- Popover is not modal. The rest of the page stays interactive. For content that must block interaction, use
<dialog>withshowModal(). - Auto popovers light-dismiss. A click outside, or Esc, closes them, and focus returns to the invoking element. Nested auto popovers close together with their ancestor chain.
- Positioning is up to you. The default is centered like a dialog. Use CSS anchor positioning (where available) or compute coordinates with
getBoundingClientRect(). - Accessibility. A
popovertargetbutton exposes the expanded state to assistive technology, but you still need meaningful labels. A popover has no role by default; addrole="menu",role="dialog"and so on as the content demands. - Not hover tooltips.
popoveralone does not open on hover; that needs extra script and care for keyboard users. - Default styles. Popovers have browser styles (border, padding, centered with
margin: auto); reset them if you position manually. togglePopover()return value is a boolean in current browsers; older versions returned nothing, so do not depend on it if you must support them. Readmatches(":popover-open")instead.
Browser support
The Popover API is part of the current baseline in recent versions of all major browsers, but it is newer than <dialog>, so check a compatibility table. CSS anchor positioning is more recent still.