Skip to content

Popover

C-06 · Components · Overlays

All elements · Popover on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for Popover.

Popover

C-06WCAG 2.2 AA · Passed #399

Anchored floating surface with arbitrary content. Uses the native popover attribute for light-dismiss; only one InfoPopover is open at a time.

Axis Values
.qf-popover__header · __body · __footer slots; body accepts data-padding="none"
.qf-info-rows label / value grid for InfoPopover content
Click to open
Document info
Type
Invoice
Date
2026-08-14
Owner
jdJane Doe
Status
Approved
Rename view

Guidance

When to use

  • Use a popover to show details about an item next to it, such as document info, without leaving the page.
  • Use a popover for a small, quick edit, such as renaming a view, with Cancel and Save in the footer.
  • Use a popover as the anchored container for pickers, such as the date picker calendar.
  • Use the InfoPopover (.qf-info-rows) for a short label and value list.

When to consider something else

  • If the content is a list of actions, use a menu. See Menu.
  • If the content is a short, non-interactive hint, use a tooltip. See Tooltip.
  • If the task needs more than a few fields or must block the page, use an overlay. See Overlay.
  • If the user must confirm a risky action, use a confirmation in its popover presentation. See Confirmation.

Usability

Do
  • Open it from a button next to the content it describes.
  • Keep it small; if it scrolls, it should probably be an overlay.
  • Give it a header that names its content, and a close button when it has no footer.
  • Keep only one InfoPopover open at a time.
Don’t
  • Don't open a popover on hover; open it on click or keyboard activation.
  • Don't nest popovers inside popovers.
  • Don't put long forms or tables in a popover.

Accessibility

Keyboard

Popover keyboard
Keys Action
Enter or Space On the trigger, opens or closes the popover.
Tab or Shift+Tab Moves through the controls inside the open popover.
Escape Closes the popover; if focus was inside, it returns to the trigger.

Roles and names

  • The popover uses the native popover attribute, which gives light dismiss with Escape and outside click.
  • The trigger carries aria-expanded and aria-controls; aria-expanded stays in sync on open and close.
  • A popover with a heading and controls should have role="dialog" and aria-labelledby pointing at its header; a picker uses role="dialog" with an aria-label.
  • The close button needs aria-label="Close".

Focus

  • The popover is not modal and does not trap focus.
  • The binding must move focus into the popover on open (the first field, or the popover itself), and place it right after the trigger in DOM order so Tab reaches it next.
  • When it closes with focus inside, focus returns to the trigger.

Other requirements

  • The popover must fit at 320 CSS px wide without horizontal scroll (1.4.10); its body scrolls at 60vh.
  • Content opened on click is not covered by 1.4.13, but it must still close with Escape.
  • The enter animation respects prefers-reduced-motion (2.3.3).

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

Popover test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (3 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (4 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- popover --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

Popover package
Source css/classic/components/overlays.css
Specimens also use Avatar · Box · Button · Card · Chip · Control · Field · Icon · Table · Text · Toolbar
Sprites sprites/icons.svg
React Not yet available: the React binding has not started.

Latest updates

No recorded changes yet.

All release notes