Skip to content
Tutorials Center
My learning

Topics

Lesson 75 of 122 ยท Interactive Elements

Popovers

Use the popover attribute to build menus, info panels and notifications. Learn auto vs manual popovers, popovertarget, toggle events and when to use dialog.

Menus that drop down from a button, a panel of extra information, a "Saved!" notification in the corner of the screen: these all pop over the rest of the page for a moment and then go away. Building them by hand used to mean juggling z-index, click-outside detection and keyboard handling.

The popover attribute turns any element into a popover with no JavaScript at all. The browser shows it above everything else, closes it when the user clicks elsewhere or presses Esc, and connects it to the button that controls it. In this lesson you'll learn the two main kinds of popovers, the attributes that open and close them, the events they fire and how they differ from dialogs.

Your first popover

Two attributes do all the work:

  • popover on the element that should pop up. It's hidden until opened.
  • popovertarget on a <button>, set to the popover's id. Clicking the button toggles the popover.
A popover with no JavaScript

Try a few things in the preview:

  • Click the button to open the menu and click it again to close it.
  • Open it and click somewhere else on the page. It closes. This is called light dismiss.
  • Open it and press Esc. It closes too.

By default, the browser shows a popover in the middle of the viewport with a simple border, because the browser has no idea where you want it. You'll learn to position it in a moment.

Browser support. The popover attribute has worked in all major browsers since 2024. In older browsers the element stays hidden and the button does nothing, so keep essential content out of popovers or provide another way to reach it.

Auto and manual popovers

The popover attribute takes a value that sets its behavior. An empty value means auto.

Value Light dismiss Other popovers
popover or popover="auto" Yes: clicking outside or pressing Esc closes it Opening it closes other auto popovers, unless it's nested inside one of them
popover="manual" No: it closes only when you tell it to Many manual popovers can be open at once

Auto popovers suit things the user opens on purpose and expects to close casually: menus, pickers, info panels. Because opening one closes the others, you never end up with three menus stacked on top of each other. A popover opened from a button inside another popover counts as nested, so a sub-menu doesn't close its parent menu.

Manual popovers suit things the page opens on its own and that should stay put until dismissed: notifications ("toasts"), a persistent help panel, a timer. Give them an explicit close button.

There is also popover="hint", a newer value designed for tooltips that appear on hover or focus. A hint popover doesn't close open auto popovers. Support is still limited at the time of writing, so stick with auto and manual unless you've checked your audience's browsers.

Controlling popovers

From HTML: popovertargetaction

By default a popovertarget button toggles its popover. The popovertargetaction attribute changes that to show or hide, which is perfect for a dedicated close button inside a manual popover:

A manual notification

Popovers use position: fixed with inset: 0 and margin: auto, which is what centers them. The CSS above overrides inset and margin to pin the notification to the bottom-right corner instead.

Only buttons can be popover controls: a <button> element, or an <input> whose type is button, submit, reset or image. A link with popovertarget does nothing, because links are for navigation.

From JavaScript

Every element has three popover methods:

  • showPopover() opens it.
  • hidePopover() closes it.
  • togglePopover() switches it. Pass true or false to force a state.

These are useful for popovers the page opens by itself, like a notification that appears after a save completes:

JavaScript
const saved = document.querySelector("#saved");

saved.showPopover();
setTimeout(() => saved.hidePopover(), 4000);

In CSS, the :popover-open pseudo-class matches a popover while it's showing, so you can style the open state or animate it.

Toggle events

Popovers fire two events every time they open or close:

  • beforetoggle fires just before the change. When the popover is about to open, you can call event.preventDefault() to stop it.
  • toggle fires just after the change.

Both events carry oldState and newState properties, each either "open" or "closed".

Watching toggle events

A typical use of beforetoggle is loading a popover's content just before it opens, so the page doesn't fetch data that nobody looks at.

Positioning popovers

A centered menu is rarely what you want. There are two ways to place a popover next to its button:

  1. CSS anchor positioning, a newer CSS feature that lets one element be positioned relative to another (its anchor). When a popover is opened by a popovertarget button, supporting browsers treat that button as its default anchor, which makes "show the menu right below the button" a few lines of CSS. Support has grown quickly, but check it before relying on it.
  2. JavaScript: read the button's position with getBoundingClientRect() and set the popover's top and left before showing it. This works everywhere.

Whichever you choose, the browser already handles the hard part: popovers live in the top layer, so they're never clipped by a parent's overflow: hidden and never hidden behind another element, whatever its z-index.

Accessibility for free

When you connect a button and a popover with popovertarget, the browser does several things for you:

  • It tells assistive technology whether the button's popover is currently expanded or collapsed.
  • When the popover opens, pressing Tab from the button moves into the popover's content, even if the popover is far away in the source code.
  • When an auto popover is dismissed with Esc, focus can return to the button that opened it.

What it can't do is decide what your popover is. A menu of links, a color picker and a block of help text are different things to a screen reader. Use the right elements inside (a list of links, a group of buttons, a paragraph), and add ARIA only when no native element expresses the meaning.

Popover or dialog?

Both appear above the page, so which should you use? Ask whether the rest of the page should stay usable.

popover <dialog> with showModal()
Rest of the page Stays usable Becomes inert
Light dismiss Yes (auto) Only with closedby or your own code
Typical use Menus, pickers, tooltips, toasts Confirmations, forms that need an answer
JavaScript needed No Yes, to call showModal() (or newer invoker commands)

Use a popover for lightweight, optional UI. Use a modal dialog when the user must deal with something before carrying on. You can even combine them: <dialog popover> creates a non-modal dialog that gets popover behavior like light dismiss.

For simple show/hide content that stays in the page flow, such as an FAQ answer, use details and summary instead.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the attribute popovertarget="help" on a button do?

    popovertarget names the id of the popover the button controls. Without popovertargetaction, it toggles the popover.
  2. 2. You open an auto popover and then click somewhere else on the page. What happens?

    Auto popovers support light dismiss, so clicking outside or pressing Esc closes them. Popovers never make the page inert.
  3. 3. Which popover type is the best fit for a notification that should stay visible until the user dismisses it?

    Manual popovers have no light dismiss and don't close each other, so they stay open until your code or a close button hides them.
  4. 4. You need the user to confirm a payment before anything else on the page can be used. What should you use?

    Only a modal dialog makes the rest of the page inert. Popovers leave the page usable, which is wrong when an answer is required first.

Summary

  • Add popover to an element to make it a popover; it's hidden until opened and shown in the top layer.
  • Connect a button with popovertarget="id"; popovertargetaction can be toggle (default), show or hide.
  • auto popovers light-dismiss and close each other; manual popovers stay open until closed explicitly.
  • Use showPopover(), hidePopover() and togglePopover() from JavaScript, and :popover-open in CSS.
  • beforetoggle and toggle events report oldState and newState.
  • Choose a popover for optional, non-blocking UI and a modal dialog when the user must respond first.

Next lesson: Global Attributes.