Skip to content
Tutorials Center
My learning

Topics

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().

HTML
<button popovertarget="menu">Menu</button>
<div id="menu" popover>Menu content</div>
JavaScript
menu.showPopover();

Try it

Declarative and scripted popovers
Detect the open state

Syntax

HTML
<element popover>                 <!-- auto (default) -->
<element popover="manual">
<button popovertarget="id" popovertargetaction="show|hide|toggle">
JavaScript
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> with showModal().
  • 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 popovertarget button exposes the expanded state to assistive technology, but you still need meaningful labels. A popover has no role by default; add role="menu", role="dialog" and so on as the content demands.
  • Not hover tooltips. popover alone 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. Read matches(":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.