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)
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>
- The
<button>carriespopovertarget="menu": each click opens or closes the element with thatid.type="button"stops it from submitting a form if the menu ends up inside one. <nav id="menu" popover>is the popover. With no value,popovermeanspopover="auto", the menu behavior.aria-labelnames the navigation, since a page can have several.- 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.
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;
}
position-area: bottom span-rightplaces it below the button, lined up with its left edge, with room to grow to the right.margin: 0.25rem 0 0leaves a 4px gap on top and removes the defaultmargin: 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.
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
autopopover 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>
- The button shows a
?, soaria-labelgives it a name that makes sense when read aloud. - The tooltip text is a paragraph with
popover: it opens on click or tap and closes on an outside click or Escape. - 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>
popovertargetaction="show"makes the first button open only; a second click won't close it. The default istoggle.popover="manual"turns off automatic closing.- The button inside targets the same
idwithpopovertargetaction="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().
| Value | Outside click | Escape | When it opens | Use it for |
|---|---|---|---|---|
auto (or empty) | Closes it | Closes it | Closes other non-nested auto popovers | Menus, click tooltips |
hint | Closes it | Closes it | Closes other hint popovers, not auto | Tooltips; not in stable Safari yet |
manual | No | No | Closes nothing | Notices, toasts |
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;
}
}
- The
[popover]rule describes the closed state: transparent and 8px higher. - The
transitionlist animates opacity and offset;displayandoverlaygetallow-discreteso the popover stays visible and in the top layer during the exit. :popover-openis the open state.@starting-stylesets where the entry starts. It goes after the:popover-openrule because both have the same specificity.- With
prefers-reduced-motion: reducethere 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:
| Feature | Chrome and Edge | Firefox | Safari | Baseline |
|---|---|---|---|---|
popover, popovertarget, :popover-open | 114 | 125 | 17 (iOS 18.3) | Yes, since January 2025 |
@starting-style (entry) | 117 | 129 | 17.5 | Yes, since August 2024 |
overlay (exit) | 117 | No | No | Limited |
popover="hint" | 151 | 153 | Not in stable (27.3 in beta) | Limited |
position-area with the implicit anchor | 133 | 147 | 26 | Full 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
popovertargeton a<div>or a link. It only works on<button>and button-type<input>. - Using
manualfor 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
hinteverywhere. Stable Safari doesn't have it and treats it asmanual. - 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 defaultmargin: autoconflicts withanchor();position-areadoesn'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">withpopovertargetand the rightid. - Menus and tooltips use
popover(auto); notices that must not close on their own usemanualwith a close button. - A tooltip button that shows only
?has anaria-label. - The menu is placed with
position-areaand still looks fine centered. - No stray
z-indexorrole="menu". - The animation uses
@starting-style, the exit is an enhancement, and there is aprefers-reduced-motionrule. - 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

Published November 19, 2026 · updated November 20, 2026