YuePopover

YuePopover is a non-modal detached surface for interactive content near a trigger. It owns positioning, collision handling, Teleport, outside/Escape closing, stacking, and conditional focus restoration. Menu navigation, modal dialog behavior, and tooltip-specific policy belong to dedicated components.

Basic interactionA real Teleport surface: click the trigger to open, Escape or an outside click to close.

<YuePopover v-model="open">
  <template #trigger="{ props }">
    <YueButton v-bind="props">Open Popover</YueButton>
  </template>
  <div>Forms, buttons, and other interactive content can go here.</div>
</YuePopover>

Placement and interactive content

Popover keeps content near its anchor. placement is the preferred position; it flips and shifts when space is limited. Form controls inside the panel remain real consumer-owned controls.

Filter panelbottom-start aligns a panel with the button edge; content clicks do not close it by default.

<YuePopover v-model="filterOpen" placement="bottom-start">
  <template #trigger="{ props }">
    <YueButton v-bind="props" variant="outline">Filters</YueButton>
  </template>
  <div class="popover-panel">
    <strong>Filter options</strong>
    <label><input type="checkbox" checked /> Show active only</label>
    <label><input type="checkbox" /> Include archived</label>
  </div>
</YuePopover>

Trigger modes

Use click for stable action panels, and hover or focus for short explanations. Each mode uses the same trigger slot props, so events are not attached to an unintended element.

Hover and focusThe tooltip role changes the ARIA relationship; it does not add menu or dialog behavior.

<YuePopover trigger="hover" role="tooltip" placement="top">
  <template #trigger="{ props }">
    <YueButton v-bind="props" variant="text">Hover for details</YueButton>
  </template>
  <span>Popover can hold interactive content; use a tooltip for plain help.</span>
</YuePopover>

<YuePopover trigger="focus" role="tooltip">
  <template #trigger="{ props }">
    <YueButton v-bind="props" variant="text">Focus for details</YueButton>
  </template>
  <span>It closes when focus leaves the trigger and content.</span>
</YuePopover>

External anchor and manual control

When there is no trigger slot, anchor supplies the positioning reference. trigger="manual" installs no automatic open/close events; the consumer owns the state.

manual + anchorA native element can be the anchor while the surface keeps the same collision and Teleport behavior.

<button ref="manualAnchor" type="button">External anchor</button>
<YuePopover
  v-model="manualOpen"
  trigger="manual"
  :anchor="manualAnchor"
  placement="right"
>
  <div>Without a trigger slot, anchor supplies the positioning reference.</div>
</YuePopover>
<YueButton variant="outline" @click="manualOpen = !manualOpen">
  {{ manualOpen ? 'Close' : 'Open' }}
</YueButton>

Close policy and events

Use close-on-content-click for short flows that finish after a selection. The close event reports trigger, outside, escape, or programmatic as its reason.

Close after content clickThe event payload lets the consumer record the reason or decide what happens next.

Last close: Not closed yet

<YuePopover
  close-on-content-click
  @close="recordClose"
>
  <template #trigger="{ props }">
    <YueButton v-bind="props">Close after content click</YueButton>
  </template>
  <button type="button">Complete and close</button>
</YuePopover>
<span>Last close: {{ lastCloseReason }}</span>

Typical use

<YuePopover placement="bottom-start">
  <template #trigger="{ props }">
    <YueButton v-bind="props">Filters</YueButton>
  </template>
  <FilterPanel />
</YuePopover>

The component flips and shifts when space is limited and updates when the viewport, scroll container, or content size changes.

See the API and Guide.