The Popover API

The Popover API gives you native popovers in the browser. You do not need to manage the top layer or light dismiss yourself.

Add the popover attribute to an element and it becomes a popover. The browser handles layering, keyboard navigation order, the relationship with the invoker, and light dismiss for auto popovers.

A popover is not modal. It does not make the rest of the page inert or trap focus like <dialog>.showModal().

HTML only, no JavaScript

The simplest setup uses a button with popovertarget.

<button popovertarget="help-tip">Show help</button>

<div id="help-tip" popover>
  <p>Click save to store your changes.</p>
</div>

Click the button and the popover opens. Click outside and it closes. That outside click behavior is called light dismiss.

You can point popovertarget at any element with a popover attribute. No event listeners required.

Auto vs manual popovers

Auto popovers use popover="auto" or just popover. Light dismiss works. Opening one normally closes another open auto popover. Nested auto popovers are the exception, so menus can contain submenus.

Manual popovers use popover="manual". They stay open until you close them with code or another toggle. Light dismiss does not apply.

<button popovertarget="status-panel">Toggle status</button>
<div id="status-panel" popover="manual">
  <p>Deploy in progress...</p>
</div>

Use manual mode for panels that should survive clicks elsewhere on the page, like a status widget or a persistent notification.

Styling with ::backdrop and :popover-open

Popovers sit in the top layer, above normal page content. Style the open state with :popover-open.

[popover] {
  border: 1px solid #ccc;
  padding: 1rem;
  border-radius: 8px;
}

[popover]:popover-open {
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

[popover]::backdrop {
  background: rgba(0, 0, 0, 0.4);
}

The ::backdrop pseudo-element covers the page behind the popover. Dim it, blur it, or leave it transparent.

JavaScript API

You can open and close popovers from code with three methods.

const tip = document.querySelector('#help-tip')

tip.showPopover()
tip.hidePopover()
tip.togglePopover()

Listen for state changes with events.

tip.addEventListener('toggle', (event) => {
  console.log(event.newState) // 'open' or 'closed'
})

Use the JS API when the trigger is not a button, or when you open the popover from app logic.

When to use it

Reach for the Popover API for tooltips, menus, and small panels. It is lighter than building a modal from scratch.

For full-screen dialogs with complex focus rules, a <dialog> element might still fit better. Popovers shine on small, contextual UI.

All modern browsers support the Popover API today. You can use it without a polyfill on current Chrome, Safari, Edge, and Firefox.