Popover pattern

Popover

Popovers extend toggle with anchored positioning, rich dismissal mechanics, and ARIA glue. They stay in sync with CSS animations, focus management, and plugin hooks so you can build command palettes, menus, or teaching bubbles without bespoke wiring.

Behavior highlights

• Adds aria-haspopup="dialog", aria-expanded, and aria-controls to triggers.
• Keeps the surface hidden until open, synchronizing hidden and aria-hidden.
• Resolves placement (top, bottom, left, right) automatically using viewport heuristics.
• Supports outside click, Escape, scroll distance, and custom dismiss controls.
• Emits lifecycle events (automagica11y:popover:toggle, automagica11y:popover:shown, automagica11y:popover:hidden, automagica11y:popover:placement).

Attribute reference

Attribute reference

Attribute	Type	Allowed values	Default	Description
data-automagica11y-popover	string | Selector	CSS selector or ID reference	Required	Connects the trigger to the popover surface.
data-automagica11y-popover-position	`auto` | `top` | `bottom` | `left` | `right`	Placement tokens	`auto`	Preferred placement for anchored positioning. Falls back automatically.
data-automagica11y-popover-outside-dismiss	boolean	`true`, `false`	`true`	Close the popover when clicking outside the surface.
data-automagica11y-popover-scroll-dismiss	boolean	`true`, `false`	`true`	Close the popover when the page scrolls beyond the configured distance.
data-automagica11y-popover-scroll-distance	number (px)	0+	0	Pixels of scroll before the popover dismisses itself.
data-automagica11y-popover-dismiss	boolean attribute	Present on any control inside the surface	N/A	Marks controls that close the popover when activated.

Events

Event	Detail payload
automagica11y:popover:ready	{ trigger, target } after hydration.
automagica11y:popover:toggle	{ trigger, target, expanded, reason } for every state change.
automagica11y:popover:shown / hidden	{ trigger, target, reason } after visibility transitions.
automagica11y:popover:dismissed	{ trigger, target, reason } when closed via outside click, Escape, scroll, or dismiss control.
automagica11y:popover:placement	{ trigger, target, placement } each time the resolved placement updates.

Pair with animate

Add data-automagica11y-animate to your trigger so automagicA11y waits for CSS transitions before the popover fully hides. This keeps opacity fades smooth without flashing hidden content.

Demo

Popover playground

Outside dismissal, scroll-dismiss, and placement events.

View source

Toggle popover

Coverage plan

1. Document how popovers interact with contexts (data-automagica11y-context="menu") once list patterns gain behaviors.
2. Provide a recipe integrating popovers with focus maps for command menus.
3. Add an example showing animated placement changes reacting to automagica11y:popover:placement.

Track progress in the Examples roadmap.