HTMLElement: showPopover() method

Baseline 2025 *
Newly available

Since January 2025, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Some parts of this feature may have varying levels of support.

The showPopover() method of the HTMLElement interface shows a popover element (i.e. one that has a valid popover attribute) by adding it to the top layer.

When showPopover() is called on an element with the popover attribute that is currently hidden, a beforetoggle event will be fired, followed by the popover showing, and then the toggle event firing. If the element is already showing, an error will be thrown.

Syntax

js
showPopover()
showPopover(options)

Parameters

options Optional

An object that can contain the following properties:

source Optional

An HTMLElement reference; programmatically defines the invoker of the popover associated with the show action, that is, its control element. Establishing a relationship between a popover and its invoker using the source option has two useful effects:

  • The browser places the popover in a logical position in the keyboard focus navigation order when shown. This makes the popover more accessible to keyboard users (see also Popover accessibility features).
  • The browser creates an implicit anchor reference between the two, making it very convenient to position popovers relative to their controls using CSS anchor positioning. See Popover anchor positioning for more details.

Return value

None (undefined).

Exceptions

InvalidStateError DOMException

Thrown if the popover is already showing.

Examples

The following example provides functionality to show a popover by pressing a particular key on the keyboard.

First, some HTML:

html
<div id="mypopover" popover>
  <h2>Help!</h2>

  <p>You can use the following commands to control the app</p>

  <ul>
    <li>Press <ins>C</ins> to order cheese</li>
    <li>Press <ins>T</ins> to order tofu</li>
    <li>Press <ins>B</ins> to order bacon</li>
    <hr />
    <li>Say "Service" to summon the robot waiter to take your order</li>
    <li>Say "Escape" to engage the ejector seat</li>
  </ul>
</div>

And now the JavaScript to wire up the functionality:

js
const popover = document.getElementById("mypopover");

document.addEventListener("keydown", (event) => {
  if (event.key === "h") {
    popover.showPopover();
  }
});

Specifications

Specification
HTML
# dom-showpopover

Browser compatibility

BCD tables only load in the browser

See also