The Popover API for Data Grid Overlays

Data grids are full of small overlays: column filter panels, header menus, cell detail previews, row action menus, date pickers. Each traditionally needed a positioning library, a z-index war, an outside-click handler, an Escape handler and careful focus management. The HTML Popover API (popover and popovertarget attributes, now Baseline across modern browsers) handles the top layer, light dismiss and Escape natively, and adds sensible keyboard behaviour. It does not decide what the overlay is — a dialog, a menu, a listbox — so semantics remain your job.

This guide belongs to tooltips, popovers & overlays in data UIs.

Spec reference

HTML popover attribute — auto (light dismiss: clicking outside or pressing Escape closes it; opening another auto popover closes it) or manual (only closes when told). Popovers render in the top layer, above everything, regardless of overflow or z-index.
popovertarget / popovertargetaction on a button — toggles, shows or hides the popover without JavaScript; the browser exposes an aria-expanded-like relationship and, in Chromium, sets aria-details/expanded semantics on the invoker.
Focus — when opened by a popovertarget button, Tab from the button moves into the popover next (even if the popover is elsewhere in the DOM), and focus returns to the invoker on light dismiss in supporting browsers.
SC 2.1.1, 2.4.3, 4.1.2 (A) — the overlay must be operable, focus order logical, and its role and name exposed.
SC 1.4.13 (AA) — applies if you open popovers on hover; with click-to-open popovers it does not.

The API removes plumbing, not design decisions.

When to use — and when not to

Use popover="auto" for transient panels that should close when users click elsewhere: column filter panels, quick-view cell details, header menus. Use popover="manual" for overlays that must stay until explicitly closed, such as a pinned comparison panel.

Do not use the Popover API as a modal. Popovers do not make the rest of the page inert and do not trap focus. For a blocking task — a confirmation, an edit form with unsaved changes — use dialog with showModal().

The misapplication: a popover element with a list of links and buttons and no role, treated as a menu. Screen readers announce nothing special on open, arrow keys do nothing, and users Tab through items one by one with no idea how many there are.

Annotated code example

<th scope="col">
  <button type="button" class="sort">Status</button>
  <!-- Invoker: no JS needed to open/close (HTML popovertarget) -->
  <button type="button" popovertarget="filter-status" aria-label="Filter Status column">⏷</button>
</th>

<!-- Popover content: semantics added by you (SC 4.1.2) -->
<div id="filter-status" popover="auto" role="dialog" aria-labelledby="fs-h">
  <h3 id="fs-h">Filter Status</h3>
  <fieldset>
    <legend class="visually-hidden">Statuses to show</legend>
    <label><input type="checkbox" checked> Paid</label>
    <label><input type="checkbox" checked> Overdue</label>
    <label><input type="checkbox"> Draft</label>
  </fieldset>
  <button type="button" popovertarget="filter-status" popovertargetaction="hide">Apply</button>
</div>

const pop = document.getElementById('filter-status');
pop.addEventListener('toggle', (e) => {
  if (e.newState === 'open') pop.querySelector('input, button').focus();   // initial focus (SC 2.4.3)
  else if (applied) status.textContent = `Status filter applied. Showing ${count()} invoices.`;
});

/* Anchor the popover to its button where CSS anchor positioning is supported */
[popover] { position-area: block-end span-inline-end; margin: 0; }

Keyboard & AT behaviour

Event	Expected behaviour	AT deviations
Enter on the invoker	Popover opens; focus to first control	Without your focus call, focus stays on the button; Tab then enters the popover
Tab past the last control	Focus moves to the element after the invoker	Expected — popovers are not traps
Escape	Closes; focus returns to invoker (auto popovers)	Verify return in Safari
Click outside	Closes (auto)	—
Screen reader on open	“Filter Status, dialog” when focus moves in	Without a role, nothing is announced

The API is the same; the semantics differ per overlay.

Integration context

Menus inside popovers follow row action menus with the menu button pattern. Filter panels are covered in focus trapping in data grid filter popovers — which explains when a filter panel should be a modal dialog instead. Positioning and reading order are discussed in anchor positioning and focus order for overlays.

Gotchas

Popovers inside grids with roving focus. The invoker sits in a cell; arrow keys move between cells. When the popover closes, focus returns to the invoker button, which may not be the grid’s current tab stop. Update the roving tabindex to the cell that contains the invoker.

Nested popovers. Opening an auto popover closes other auto popovers unless they are ancestors (in the DOM or via invoker). A date picker inside a filter popover must be a descendant, or opening it closes the filter panel.

Hover-triggered popovers. popover does not open on hover by itself. If you add hover opening (for previews), you take on 1.4.13 obligations — see hover cards.

Framework notes

The API works in any framework because it is just attributes. In React 19, popover and popoverTarget are supported props; earlier versions need lowercase attributes. In Vue and Angular, bind the attributes directly. Component libraries are migrating: some now render menus and selects with popover for top-layer behaviour while keeping their own ARIA — check that they still set roles and focus.

// React 19
<button popoverTarget="row-menu-41" aria-label="Actions for INV-1041">⋯</button>
<div id="row-menu-41" popover="auto" role="menu" aria-label="Actions for INV-1041">…</div>

Worked example

A grid with eight columns had eight hand-built filter panels, each with its own outside-click handler; two of them stayed open when Escape was pressed, and one rendered underneath the sticky header. Rebuilding them with popover="auto" removed about 300 lines of plumbing and fixed the layering. The audit still found one issue the API could not fix: the panels had no role or name, so screen reader users heard nothing when focus moved in. Adding role="dialog" and a heading resolved it.

Testing checklist

Each popover has a role and accessible name that match its content.
Opening moves focus to the first meaningful element.
Escape and outside click close auto popovers and return focus to the invoker.
Modal tasks use dialog with showModal(), not popovers.
Popovers inside grids restore the grid's roving tab stop on close.

Design system notes

Base overlay components on the Popover API to remove positioning and layering bugs, but keep role-specific components — Menu, FilterPanel, Preview — on top so semantics and keyboard models stay correct. Document which overlays are auto and which are manual.

FAQ

Is a popover accessible by default?

Partly. You get Escape, light dismiss and top-layer rendering. You still need a role, a name, initial focus and the right keyboard model inside.

Does the Popover API trap focus?

No. It is intentionally non-modal. Use a modal dialog when focus must be contained.

Will screen readers announce a popover opening?

Only if focus moves into it and it has a role and name, or if you announce it. Opening alone is not announced.

Can I use popover for tooltips?

Yes, with popover=“hint” in browsers that support it, or manual popovers controlled on hover and focus. You must then meet 1.4.13 yourself.

What about older browsers?

The API is Baseline in current Chrome, Edge, Firefox and Safari. For older targets, a polyfill exists, or fall back to your previous overlay implementation.

Anchor positioning and focus order — placing overlays without breaking order
Focus trapping in filter popovers — when to trap instead
Native dialog versus custom focus traps — modal overlays

← Back to Tooltips, Popovers & Overlays in Data UIs