Overview & Philosophy
ln-popover is applied to a popup container via data-ln-popover id="...", paired with trigger buttons anywhere in the DOM via data-ln-popover-for="...". When triggered, it sets popover="manual", invokes showPopover() to elevate into the browser's top layer without clipping or z-index issues, calculates boundary-aware anchor coordinates, and writes data-ln-popover="open". On outside clicks or pressing Escape, it calls hidePopover(), writes data-ln-popover="closed", and restores keyboard focus to the trigger.
It provides viewport-aware positioning, automatic boundary flip placement, and full LIFO (Last-In, First-Out) keyboard dismissal for rich contextual cards, action menus, and filter flyouts.
The Popover Doctrine
The contract is absolute: the active state lives solely in the data-ln-popover attribute on the popover element, and the DOM is the single source of truth. Triggers, keyboard esc handlers, click-outside rules, and custom scripts all change state by writing to the attribute. A single MutationObserver callback runs the entire presentation, positioning, and focus management pipeline.
Key Features & Viewport Awareness
- Automatic Flipping (Auto-Flip): You can set a preferred position (
data-ln-popover-position="top|bottom|left|right"). If there isn't enough room in the viewport, the positioning engine automatically flips the popover to the opposite side to keep it fully visible. - Focus Management: When a popover opens, focus moves automatically into the popover dialog. When closed, focus is returned back to the triggering element, maintaining a smooth accessibility path.
- Dismissal Rules: Clicking anywhere outside the popover (or its trigger button) closes it. Additionally, pressing
ESCcloses the most recently opened popover in a LIFO stack. - Nesting & Composition: Opening popover B from inside popover A leaves A open. ESC will close B first, and then A.
For the complete developer reference, see the ln-popover README and the architecture reference.
1. Basic — Account popover
Click the avatar button to open the account popover. Focus moves into the popover on open. Click outside or press ESC to close.
user@example.com
2. Position attribute
Four buttons with explicit preferred placement. The popover flips to the opposite side if the preferred side doesn't fit.
Preferred: top. Check data-ln-popover-placement in DevTools.
Preferred: bottom.
Preferred: left.
Preferred: right.
3. Auto-flip near viewport edge
The button below is pushed to the far right. Its popover prefers right but flips to left because there is no room on the right. Inspect data-ln-popover-placement after opening — it should read left.
I flipped to the left because there was no space on the right. data-ln-popover-placement = left.
4. Nested popovers — A stays open when B opens
Open popover A, then click the button inside A to open popover B. Both A and B should be open simultaneously. Press ESC once to close B, again to close A.
Popover A — I will stay open when B opens.
Popover B — A is still open. Press ESC to close me first.
5. Form inside popover
Interactive content inside a popover. Tab navigates the form fields; the popover stays open. Submit fires the form action.
6. aria-expanded live indicator
The trigger button below has its aria-expanded wired automatically. Watch the status line update as you open and close the popover.
aria-expanded on trigger = false
Popover is open. Check the status line above.