AddThisFeature

Popover Positioning Engine

Place anchored panels where the user expects them and never off the edge of the screen.

involved Components & Primitives

What it adds

A single positioning layer that places any anchored element relative to its trigger and keeps it inside the viewport.

What your agent is told to do

5
  1. 1

    Find everything the app anchors to a trigger — menus, tooltips, date pickers, select lists, autocomplete panels, colour pickers — and move them all onto one positioning layer rather than leaving each with its own offset arithmetic.

  2. 2

    Express placement as a preferred side and alignment, then let the engine flip to the opposite side, slide along the anchor, or reduce the panel's available height when the preferred placement does not fit.

  3. 3

    Recompute position when the anchor moves for any reason: page scroll, scroll inside a container, window resize, content changing size, or the anchor itself being repositioned.

  4. 4

    Measure against the real rendered geometry rather than assumed offsets, so panels stay correct under browser zoom, page-level scaling, and ancestors with transforms applied.

  5. 5

    Do not position by absolute coordinates measured once at open. The first frame will be right and every subsequent scroll will leave the panel stranded away from its trigger.

Edge cases it handles

7
  • When the preferred side has insufficient room, the engine must flip to the opposite side, shift along the cross axis to stay in view, or constrain the panel's height and let it scroll internally — and it must pick one deterministically rather than oscillating between two placements.
  • An anchor inside a scrolling container moves independently of the page. Track that container's scrolling too, and hide or detach the panel when the anchor scrolls out of sight rather than leaving it floating over unrelated content.
  • Browser zoom, transformed ancestors, and fractional device pixel ratios all break naive coordinate arithmetic and leave the panel a few pixels adrift or badly misplaced. Measure real geometry at position time.
  • A pointer arrow must be repositioned along with the panel after any flip or shift, and clamped so it still touches the anchor and never overhangs the panel's own rounded corner.
  • Two anchored panels open at once need a defined stacking order, so a menu opened from inside a dialog renders above it rather than behind.
  • A panel wider than the viewport on a small screen must not simply be pushed inward until it covers its own trigger; below a defined width, fall back to a full-width sheet.
  • Position must be settled before the panel becomes visible, or the user sees it appear in the wrong place and slide into position.

Definition of done

9
  • Every anchored surface in the app is positioned by the same engine.
  • No anchored panel is ever clipped by or extends beyond the viewport edge.
  • Panels follow their anchor through page scroll, container scroll, and window resize.
  • Placement is stable and does not flicker between two sides at a boundary size.
  • Arrows remain aligned to the anchor after a flip or shift.
  • Positioning is correct under browser zoom and inside transformed ancestors.
  • A panel is fully positioned before it is painted, with no visible jump.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.