◇

Popper

4 parts

The context provider for a popper. It coordinates positioning between PopperAnchor (the reference element), PopperContent (the floating element placed against it), and PopperArrow, sharing the registered anchor via context. It renders only its slot and adds no DOM of its own, so wrap the anchor and content in it to build tooltips, popovers, dropdown menus, and other floating UI.

Source

Anatomy

Import the parts and compose them. Each part forwards attributes to its underlying element.

vue

import {
  PopperRoot,
  PopperAnchor,
  PopperContent,
  PopperArrow,
} from '@robonen/primitives/overlays/popper';

<PopperRoot>
  <PopperAnchor />
  <PopperContent />
  <PopperArrow />
</PopperRoot>

API Reference

PopperRoot

Root

The context provider for a popper. It coordinates positioning between `PopperAnchor` (the reference element), `PopperContent` (the floating element placed against it), and `PopperArrow`, sharing the registered anchor via context. It renders only its slot and adds no DOM of its own, so wrap the anchor and content in it to build tooltips, popovers, dropdown menus, and other floating UI.

No props or events — renders its element and forwards attributes.

PopperAnchor

Anchor

Marks the element that `PopperContent` positions itself against. Renders its child and registers it with the `PopperRoot` as the positioning reference; pass `reference` to anchor to a virtual or external element instead of the rendered DOM node. Optional — when omitted, the content falls back to its own `reference` prop or the nearest registered anchor.

Prop	Type	Default	Description
`reference`?	`ReferenceElement`	—	Custom reference element for positioning. If not provided, uses the rendered element.

PopperContent

Content

The floating element positioned against the anchor. This is the workhorse of the Popper building block: it runs Floating UI (offset, flip, shift, size, arrow, hide) to place itself on the chosen side/alignment, keeps the position updated on scroll/resize/layout shift, avoids collisions with the viewport or a custom boundary, and exposes `--popper-*` CSS variables plus `data-side` / `data-align` attributes for styling and transform-origin. Use the Popper parts to build any anchored overlay — tooltips, popovers, menus, selects — where content must follow a trigger and stay on-screen. Place it inside a `PopperRoot` (so it can read the registered anchor) and emit `placed` once the first position settles.

Prop	Type	Default	Description
`side`?	`Side`	`'bottom'`	Preferred side of the anchor.
`sideOffset`?	`number`	`0`	Distance in pixels from the anchor.
`sideFlip`?	`boolean`	`true`	Flip to the opposite side on collision.
`align`?	`Align`	`'center'`	Preferred alignment against the anchor.
`alignOffset`?	`number`	`0`	Offset in pixels from the alignment edge.
`alignFlip`?	`boolean`	`true`	Flip alignment on collision.
`avoidCollisions`?	`boolean`	`true`	Reposition to prevent boundary overflow.
`collisionBoundary`?	`Array<Element \| null> \| Element \| null`	`[]`	Collision boundary element(s).
`collisionPadding`?	`number \| Partial<Record<Side, number>>`	`0`	Distance from boundary for collision detection.
`arrowPadding`?	`number`	`0`	Padding between arrow and content edges.
`hideShiftedArrow`?	`boolean`	`true`	Hide arrow when it can't be centered.
`sticky`?	`'always' \| 'partial'`	`'partial'`	Sticky behavior on the align axis.
`hideWhenDetached`?	`boolean`	`false`	Hide when anchor is fully occluded.
`positionStrategy`?	`'absolute' \| 'fixed'`	`'fixed'`	CSS position strategy.
`updatePositionStrategy`?	`'always' \| 'optimized'`	`'optimized'`	Position update strategy.
`disableUpdateOnLayoutShift`?	`boolean`	`false`	Disable layout-shift-based position update.
`prioritizePosition`?	`boolean`	`false`	Force content to stay within the viewport.
`reference`?	`ReferenceElement`	—	Custom reference element, overrides the anchor.

PopperArrow

Arrow

An optional arrow/pointer rendered inside `PopperContent` that points back at the anchor. It reads the resolved side and arrow offset from the content context to position and rotate itself against the correct edge, and hides automatically when it cannot be centered. By default it renders a real `<svg>` triangle (a `rounded` variant is available); supply your own SVG/element via the default slot, or switch the rendered element with `as`. Must be a child of `PopperContent`.

Prop	Type	Default	Description
`width`?	`number`	`10`	Arrow width in pixels.
`height`?	`number`	`5`	Arrow height in pixels.
`rounded`?	`boolean`	`false`	Render the rounded variant of the default arrow path. Ignored when a custom default slot or `as="template"` is used.