Skip to content

Popover API: menus and tooltips without JavaScript

From the work/ 11 min read

The Popover API in practice: a menu, a tooltip and a notice in plain HTML, light dismiss, popover="manual", CSS animation, focus and browser support.

  • JavaScript
In this article (9)
  1. Popover API basics: popover and popovertarget
  2. Light dismiss: closing on outside click and Escape
  3. popover="manual" for notices that stay put
  4. Animating a popover with CSS
  5. Accessibility and focus
  6. Browser support
  7. Common mistakes
  8. Frequently asked questions
  9. Checklist

The Popover API lets you build menus, tooltips and notices without JavaScript: add popover to the element and popovertarget to the button. The browser puts it in the top layer, closes it on an outside click or Escape, and wires the button to the menu for keyboard users. It has been Baseline since January 2025.

Below are the three uses with complete code: an account menu, a tooltip that opens on click, and a notice that only its own button closes. We ran them in Chromium 151, Firefox 155 and WebKit 26.5 with Playwright, and we point out where the engines behave differently.

Popover API basics: popover and popovertarget

It is two HTML attributes. popover turns an element into a popover: hidden until something opens it. popovertarget, on a <button>, takes the popover's id and toggles it on every click. Per MDN's Popover API reference, popovertarget works on <button> and button-type <input> elements, not on a <div> or a link. Here is a store's account menu:

<button type="button" popovertarget="menu">My account</button>
<nav id="menu" popover aria-label="My account">
  <ul>
    <li><a href="/account/orders">Orders</a></li>
    <li><a href="/account/addresses">Addresses</a></li>
    <li><a href="/account/logout">Log out</a></li>
  </ul>
</nav>
  1. The <button> carries popovertarget="menu": each click opens or closes the element with that id. type="button" stops it from submitting a form if the menu ends up inside one.
  2. <nav id="menu" popover> is the popover. With no value, popover means popover="auto", the menu behavior.
  3. aria-label names the navigation, since a page can have several.
  4. Inside are plain links in a list. You don't need role="menu": that role promises arrow-key navigation you would have to write yourself.

When it opens, the popover moves to the top layer, the same layer modal dialogs and fullscreen elements use. It sits above everything with no z-index. We checked by putting the popover inside a 10px box with overflow: hidden and a transform, under a fixed layer with the maximum z-index: all three engines drew it full size and on top.

a button opens the menu in the top layerthe pageMy accountpopovertarget="menu"the rest of the contenttop layerOrdersAddressesLog outid="menu" popoverabove everythingno z-index; overflow: hidden does not clip itEscape or a click outside closes itone button, one id, zero JavaScriptsource: MDN, Popover API and top layer

Scroll the figure sideways to see all of it

Position is the missing piece. By default the browser centers a popover in the viewport (position: fixed, inset: 0, margin: auto), which suits a notice but not a menu. To pin it to the button you use CSS anchor positioning, which places one element relative to another, its anchor. With popovertarget you don't declare the anchor: MDN explains that the button becomes the popover's implicit anchor and that position-area picks it up on its own.

/* The menu sits under its button (anchor positioning). */
#menu {
  position-area: bottom span-right;
  margin: 0.25rem 0 0;
}
  1. position-area: bottom span-right places it below the button, lined up with its left edge, with room to grow to the right.
  2. margin: 0.25rem 0 0 leaves a 4px gap on top and removes the default margin: auto, which would center it inside the area.

In all three engines the menu landed 4px below the button with its left edge aligned. If a browser doesn't understand position-area, the menu shows up centered in the viewport: odd-looking, but it still works.

the attributes on one cardattributevaluewhat it doespopoverautooutside click and Escape close itpopoverhintfor tooltips; manual in Safaripopovermanualonly you close itpopovertargetidthe button that controls itpopovertargetactiontoggle|show|hidetoggle by default:popover-opencssstyles the open statewithout hint support, the browser treats it as manualPopover API attributessource: MDN, popover attribute and Popover API

Scroll the figure sideways to see all of it

Light dismiss: closing on outside click and Escape

An auto popover closes itself in three ways, none of which need code. MDN calls it light dismiss (Using the Popover API):

  • A click or tap outside closes it.
  • Escape closes it. MDN describes this as a browser-specific mechanism; on desktop it is the Esc key.
  • Opening another auto popover closes the open one, unless one is nested in the other, like a submenu.

A second click on the same button closes it too, because popovertarget toggles. That is the behavior you want for a tooltip that opens on click or tap, often called a toggletip:

<p>Express shipping
  <button type="button" popovertarget="shipping-help" aria-label="What is express shipping?">?</button>
</p>
<p id="shipping-help" popover>Arrives in one business day within the city.</p>
  1. The button shows a ?, so aria-label gives it a name that makes sense when read aloud.
  2. The tooltip text is a paragraph with popover: it opens on click or tap and closes on an outside click or Escape.
  3. Because it is auto, opening it closes the menu if the menu was open. That is what happened in all three engines.

Without JavaScript, the tooltip opens on click, not on hover. There is a value designed for tooltips, popover="hint": it doesn't close auto popovers when it shows, and it closes other hint popovers. But stable Safari doesn't support it yet, and a browser that doesn't know it treats it as manual; WebKit 26.5 reported the attribute as "manual". That's why the example uses auto.

popover="manual" for notices that stay put

A shipping notice shouldn't vanish because someone tapped the page. With popover="manual" there is no light dismiss: neither an outside click nor Escape closes it, several can be open at once, and it neither closes nor gets closed by auto popovers. You close it, with a button:

<button type="button" popovertarget="notice" popovertargetaction="show">Show shipping notice</button>
<div id="notice" popover="manual">
  <p>Orders placed today ship on Monday.</p>
  <button type="button" popovertarget="notice" popovertargetaction="hide">Close notice</button>
</div>
  1. popovertargetaction="show" makes the first button open only; a second click won't close it. The default is toggle.
  2. popover="manual" turns off automatic closing.
  3. The button inside targets the same id with popovertargetaction="hide", so it only closes.

In our runs the notice stayed open after an outside click, after Escape, and while the menu opened and closed on top of it. If the notice must appear by itself on page load, that does take one line of JavaScript: document.getElementById("notice").showPopover().

ValueOutside clickEscapeWhen it opensUse it for
auto (or empty)Closes itCloses itCloses other non-nested auto popoversMenus, click tooltips
hintCloses itCloses itCloses other hint popovers, not autoTooltips; not in stable Safari yet
manualNoNoCloses nothingNotices, toasts
three uses, three ways of closingmenupopover="auto"click the buttoncloses on outside clickand on Escapeone open at a timee.g. My accounttooltippopoverclick or tap, not hoverone short sentencecloses like the menuhint: not in Safari yete.g. express shipping ?noticepopover="manual"ignores outside clicksignores Escapecloses with its buttonseveral at oncee.g. ships on Mondayauto closes other auto popovers; manual stays outthree values: auto, hint and manualtested in Chromium 151, Firefox 155 and WebKit 26.5

Scroll the figure sideways to see all of it

Animating a popover with CSS

A closed popover is display: none, so a plain transition never shows. MDN's recipe uses @starting-style for the entry and transition-behavior: allow-discrete so that display and overlay wait for the exit to finish:

/* Fade in and out. overlay keeps it in the top layer while it closes. */
[popover] {
  opacity: 0;
  translate: 0 -0.5rem;
  transition:
    opacity 0.15s,
    translate 0.15s,
    overlay 0.15s allow-discrete,
    display 0.15s allow-discrete;
}
[popover]:popover-open {
  opacity: 1;
  translate: 0 0;
}
@starting-style {
  [popover]:popover-open {
    opacity: 0;
    translate: 0 -0.5rem;
  }
}

/* No movement for people who asked for less of it. */
@media (prefers-reduced-motion: reduce) {
  [popover] {
    transition: none;
  }
}
  1. The [popover] rule describes the closed state: transparent and 8px higher.
  2. The transition list animates opacity and offset; display and overlay get allow-discrete so the popover stays visible and in the top layer during the exit.
  3. :popover-open is the open state.
  4. @starting-style sets where the entry starts. It goes after the :popover-open rule because both have the same specificity.
  5. With prefers-reduced-motion: reduce there is no transition: our runs found no animations at all.

What we measured: the entry animated in all three engines. The exit animated only in Chromium; in Firefox 155 and WebKit 26.5 the popover disappeared at once. That matches MDN's compatibility data, which lists overlay in Chrome and Edge only. Nothing breaks, you just lose the exit animation. If what you want to animate is the move from one page to another, that's a different API: cross-document view transitions.

Accessibility and focus

According to MDN, when a button controls a popover through popovertarget, the browser sets up an implicit aria-expanded and aria-details relationship between them, and the popover becomes next in the tab order after the button. In Chromium's accessibility tree the button reported expanded=true while the menu was open. The keyboard path worked in all three engines: Enter on the button opens the menu, Tab moves to its first item, and Escape closes it and puts focus back on the button.

Two WebKit differences are worth knowing. First, Tab didn't reach the links in the menu: like Safari's default setting, WebKit only tabs to buttons and form fields, and links are reached with Option+Tab; with buttons in the menu, the path matched the other engines. Second, a mouse click doesn't focus the button, so after opening with a click and closing with Escape, focus landed on <body>.

A popover is not modal: it doesn't block the rest of the page or trap focus. If you need that, say to confirm emptying the cart, use <dialog> with showModal(). Showing a popover also doesn't move focus into it, so a notice that has to be heard needs a live region too, such as a role="status" element already on the page. For forms, the same care with names and messages is covered in accessible forms with WCAG 2.2.

Browser support

The basic popover has been Baseline since January 27, 2025. A web.dev post from April 2024 announced it earlier, and web.dev corrected it on February 7, 2025: on iOS an outside click didn't close the popover until Safari 18.3. MDN's popover attribute page still shows the old date. Everything else ships piece by piece, per MDN's compatibility data and webstatus.dev, both read on November 19, 2026:

FeatureChrome and EdgeFirefoxSafariBaseline
popover, popovertarget, :popover-open11412517 (iOS 18.3)Yes, since January 2025
@starting-style (entry)11712917.5Yes, since August 2024
overlay (exit)117NoNoLimited
popover="hint"151153Not in stable (27.3 in beta)Limited
position-area with the implicit anchor13314726Full anchor positioning: limited

On positioning: webstatus.dev lists full anchor positioning as limited availability (Chrome and Edge 157, Safari 27; Firefox not complete yet), but the part this article uses, position-area with the implicit anchor, has been in Firefox since 147 and Safari since 26 per MDN, and it worked in all three test engines. Where it's missing, the menu shows up centered.

Common mistakes

  • Putting popovertarget on a <div> or a link. It only works on <button> and button-type <input>.
  • Using manual for a menu. You lose outside-click and Escape closing and would have to write them.
  • Fighting z-index. An open popover is already in the top layer; if it's covered, it probably wasn't opened as a popover.
  • Counting on hint everywhere. Stable Safari doesn't have it and treats it as manual.
  • Assuming the exit animation runs. It only runs in Chrome and Edge; make sure the instant close looks fine too.
  • Using anchor() without resetting the margin. MDN warns that the default margin: auto conflicts with anchor(); position-area doesn't have that problem, but setting the margin is still a good idea.
  • Adding role="menu" to a list of links. It promises arrow keys you didn't build.
  • Using a popover as a modal. It doesn't block the page; that's what <dialog> is for.

Frequently asked questions

When should I use popover and when dialog?

Popover for things that live alongside the page: menus, tooltips, notices. <dialog> with showModal() when the person must respond before going on, because it makes the rest of the page inert. You can combine them: <dialog popover> is valid and stays non-modal.

Can the tooltip open on hover without JavaScript?

Not in every browser. A newer attribute, interestfor, opens a popover on hover or focus, but per webstatus.dev it is only in Chrome and Edge. Today, without JavaScript, the tooltip opens on click or tap, which also works the same on mobile, where there is no hover.

popovertarget or commandfor?

commandfor with command="toggle-popover" (also show-popover and hide-popover) does the same job and covers other commands, like opening a <dialog>. It has been Baseline since December 2025 and worked in all three test engines. popovertarget has been in browsers longer; for a popover, either one works.

How do I know when it opens, say for analytics?

Listen for the toggle event, which carries oldState and newState: menu.addEventListener("toggle", (e) => console.log(e.newState)) logged closed>open and open>closed in our runs. If you need to stop it from opening, beforetoggle fires first and preventDefault() cancels it.

Checklist

  • The control is a <button type="button"> with popovertarget and the right id.
  • Menus and tooltips use popover (auto); notices that must not close on their own use manual with a close button.
  • A tooltip button that shows only ? has an aria-label.
  • The menu is placed with position-area and still looks fine centered.
  • No stray z-index or role="menu".
  • The animation uses @starting-style, the exit is an enhancement, and there is a prefers-reduced-motion rule.
  • You tested with the keyboard: Enter opens, Tab goes in, Escape closes and returns to the button.
  • Anything that must be modal uses <dialog>.

Saw this on Instagram? Every Reel guide is at ecomlabs.dev/guides.

Written by

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published November 19, 2026 · updated November 20, 2026

← Blog