Popover

Problem Context

• A field, row, map pin, chart mark, term, or object needs explanation or light editing without navigating away.
• The content is more than a tooltip label but smaller than a dialog, drawer, sheet, or page.
• Users should keep seeing and using the surrounding page unless they are interacting directly inside the popover.
• The implementation can maintain anchor position, focus order, outside dismissal, Escape behavior, and screen reader relationships.

Selection Rules

• Choose popover when a local trigger needs a compact contextual layer with short copy, a few actions, or light controls that belong to that exact anchor.
• Use menu button when the popup is primarily a command list and should use menu item roles, active-item movement, and command activation behavior.
• Use modal dialog when users must complete or cancel a compact blocking task before returning to the page.
• Use sheet when the surface needs more room, sticky actions, adaptive sizing, or protected dirty-state dismissal.
• Use disclosure details when the content can stay inline and should remain part of the page flow after expansion.
• Use inline text, validation, or an inline message for essential instructions that must not disappear on light dismissal.
• Use tooltip-style help only for short noninteractive hints; do not hide required instructions, form controls, or complex content in hover-only behavior.
• Use a full page when the interaction needs routing, long reading, saved progress, or multiple steps.

Required States

• Closed trigger state with visible label, icon name, or field relationship.
• Open anchored state with position tied to the trigger, selected text, field, or object.
• Collision state where the surface flips, shifts, or changes side before it clips or disconnects.
• Interactive focus state when controls inside the popover are reachable after the trigger in the keyboard order.
• Clean light-dismiss state through outside click, Escape, close button, or another trigger.
• Applied state where a local choice updates the anchor value and closes the popover.
• Anchor changed or scrolled state where the popover follows, closes, or clearly reanchors.
• Small-screen state where the same contract still works without becoming an unlabeled modal or hidden sheet.

Interaction Contract

• The trigger name and visible placement make clear which object or field the popover belongs to.
• Opening from keyboard moves focus to the first meaningful control inside the popover or keeps focus on the trigger only when the content is purely informational and still reachable.
• Focusable content inside the popover follows the invoker in the tab order and does not trap focus like a modal dialog.
• Escape closes the popover and returns focus to the trigger or local result.
• Outside click or another local trigger closes a clean auto popover without applying a hidden action.
• A manual popover has an explicit close path and a reason to stay open after outside interaction.
• Placement updates with scrolling, viewport edges, zoom, and responsive changes so the surface remains visually tied to its anchor.
• If a control inside the popover changes the anchor value, the update is visible at the anchor after close.

Implementation Checklist

• Identify the exact anchor element and name the relationship in trigger text, aria attributes, or visible copy.
• Choose auto, manual, or hint behavior based on whether light dismissal and one-at-a-time behavior match the task.
• Keep content brief and remove unrelated navigation, long forms, tables, and multi-step workflows.
• Implement Escape, outside click, close button when needed, opener toggling, and focus return consistently.
• Put popover controls in a predictable keyboard order near the invoker and avoid modal focus traps for nonmodal popovers.
• Handle placement collision, scroll containers, clipping, portals, zoom, and small screens without detaching from the anchor.
• Use semantics that match content: ordinary buttons and links for rich popovers, menu roles only for menu behavior, and dialog semantics only for truly dialog-like surfaces.
• Test keyboard, touch, screen readers, high zoom, viewport edges, nested overlays, and anchor changes.

Common Generated-UI Mistakes

• Using a popover as a hidden modal, drawer, sheet, command menu, or full workflow.
• Showing required instructions only in a hover-only layer that cannot be opened or kept open on touch and keyboard.
• Letting the popover appear detached from its trigger after scrolling, collision, or portal rendering.
• Putting long forms or unsaved edits in a surface that can light-dismiss without review.
• Mixing menu roles with arbitrary buttons, links, inputs, and explanatory content.
• Opening several overlapping popovers at once with no ownership, close order, or focus return.
• Failing to restore focus to the invoker after Escape, close, outside click, or applied selection.

Critique Questions

• What exact field, object, or selection anchors this popover?
• Is the content local and brief enough to stay nonmodal?
• Does the surface need command-menu keyboard behavior, dialog modality, a sheet, or inline disclosure instead?
• What happens on Escape, outside click, anchor scroll, viewport collision, and trigger reactivation?
• Where does focus move on open, inside the popover, after applying a choice, and after dismissal?
• Is any required instruction hidden in a dismissible or hover-only layer?