Popover
Floating panel anchored to a trigger element with auto-positioning, flip behavior, and backdrop dismissal.
import { Popover } from "phoundry-ui";Basic Popover
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { Popover } from "phoundry-ui";</script>
<Popover> {#snippet trigger(toggle)} <Button onclick={toggle}>Open Popover</Button> {/snippet} <div class="min-w-48 rounded-lg border border-border-muted bg-surface-base p-3 shadow-lg" > <p class="mb-1 text-sm font-medium text-txt-primary">Popover Title</p> <p class="text-xs text-txt-secondary"> This is a basic popover with some content. </p> </div></Popover>Placement Options
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { Popover } from "phoundry-ui"; import type { PopoverPlacement } from "phoundry-ui";
const placements: PopoverPlacement[] = ["top", "bottom-end", "right", "left"];</script>
<div class="flex flex-wrap items-center gap-2"> {#each placements as p (p)} <Popover placement={p}> {#snippet trigger(toggle)} <Button size="sm" onclick={toggle}>{p}</Button> {/snippet} <div class="rounded-lg border border-border-muted bg-surface-base p-2 shadow-lg" > <p class="text-xs whitespace-nowrap text-txt-secondary">Placed: {p}</p> </div> </Popover> {/each}</div>Offset & flip
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { Popover } from "phoundry-ui";</script>
<p class="mb-2 text-xs text-txt-secondary"> <code>offset</code> grows the gap from the anchor; <code>flip=false</code> keeps the requested placement even near viewport edges (may overflow - test on small screens).</p><div class="flex justify-center py-4"> <Popover placement="bottom" offset={16}> {#snippet trigger(toggle)} <Button size="sm" onclick={toggle}>offset 16</Button> {/snippet} <div class="rounded-lg border border-border-muted bg-surface-base p-3 text-xs shadow-lg" > Extra breathing room from the trigger. </div> </Popover></div>Non-dismissible backdrop
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { Popover } from "phoundry-ui";
let stickyOpen = $state(false);</script>
<p class="mb-2 text-xs text-txt-secondary"> Outside clicks no longer close the surface - pair with a button that calls <code >toggle()</code > or clears <code>bind:open</code>.</p><div class="flex flex-wrap items-center gap-2"> <Popover dismissible={false} bind:open={stickyOpen}> {#snippet trigger(toggle)} <Button size="sm" onclick={toggle}>Open sticky</Button> {/snippet} <div class="min-w-52 rounded-lg border border-border-muted bg-surface-base p-3 text-xs shadow-lg" > <p class="mb-2 text-txt-secondary">Backdrop clicks do nothing.</p> <Button size="sm" variant="primary" onclick={() => (stickyOpen = false)} >Close</Button > </div> </Popover></div>Controlled Open
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { Popover } from "phoundry-ui";
let controlledOpen = $state(false);</script>
<div class="flex items-center gap-2"> <Popover bind:open={controlledOpen}> {#snippet trigger(toggle)} <Button onclick={toggle}>Toggle Popover</Button> {/snippet} <div class="min-w-48 rounded-lg border border-border-muted bg-surface-base p-3 shadow-lg" > <p class="text-sm text-txt-primary">Controlled popover</p> <p class="mt-1 text-xs text-txt-secondary">Open: {controlledOpen}</p> </div> </Popover> <Button size="sm" variant="outline" onclick={() => (controlledOpen = false)} disabled={!controlledOpen}>Close Externally</Button ></div>Programmatic overlay
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { getPopoverManager } from "phoundry-ui";
const programmaticPopover = getPopoverManager();</script>
{#snippet programmaticDemo()} <div class="rounded-lg border border-border-muted bg-surface-base px-3 py-2 text-xs shadow-lg" > Programmatic popover body </div>{/snippet}
<p class="mb-2 text-xs text-txt-secondary"> Use when the anchor is not a stable child of the overlay host (selection rects, hover targets). Mount <code>PopoverOverlay</code> once in the root layout; optional <code>content</code> on <code>open()</code> overrides the default child.</p><Button size="sm" onclick={(e) => { const el = e.currentTarget as HTMLElement; programmaticPopover.open({ anchor: el, placement: "top", ariaLabel: "Demo programmatic popover", content: programmaticDemo, }); }}> Open anchored to this button</Button>Both Popover APIs use the same internal floating surface and Context Menu panel styling. Placement, modal/nonmodal behavior, dismissal, and content ownership continue to use the existing Popover props and manager options.
API
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
openbindable | boolean | false | Whether the popover is open. Bindable. |
onOpenChange | (open: boolean) => void | — | Callback when open state changes. |
placement | PopoverPlacement | 'bottom-start' | Positioning relative to the trigger element. |
offset | number | 4 | Gap in pixels between trigger and popover. |
flip | boolean | true | Flip to opposite side if there is not enough space. |
dismissible | boolean | true | Close on an outside pointer press, including touch. |
modal | boolean | true | Whether a backdrop blocks interaction outside the panel. Set false for selection toolbars or other controls that keep the page interactive. |
class | string | '' | Additional CSS classes for the floating panel. |
trigger | Snippet<[toggle: () => void]> | — | Trigger region - receives toggle. Optional only if you drive open entirely from the outside (unusual). |
children | Snippet<[]> | — | Popover body content. |
Usage tips
- The
triggersnippet receives atogglefunction - call it on click to open/close. - Use
bind:openfor controlled state - you can open/close from external buttons or logic. - With
flip: true(default), the popover repositions if it would overflow the viewport. - Set
dismissible: falseto prevent closing on outside clicks (useful for forms). - The floating panel uses
role="dialog"; focus management is minimal - trap focus inside when hosting complex widgets. Escapecloses the top contextual owner regardless ofdismissible(handled onwindow).
With the default modal: true, outside pointer presses consume the dismissal gesture. With modal: false, the page receives those presses normally; dismissible: true also closes the panel. Presses within either panel preserve native focus, caret, form submission, and editing behavior.
Application Back
Declarative Popover and programmatic PopoverOverlay register their existing close behavior with getContextualDismissal() while open. Import it from phoundry-ui; read its reactive active property when coordinating application focus, and call back() before dismissing the application surface beneath it. The call closes only the latest mounted menu level or Popover and returns true when consumed. Closing preserves the usual onOpenChange or manager callback behavior, and registration is released on close and teardown.
dismissible: false controls outside pointer dismissal; Escape and semantic Back still close the Popover. This interface does not manage application navigation, dialogs, or browser history.
Context menus and both Popover forms portal their roots to document.body. Opening or promoting an owner places its root after existing contextual owners so paint order follows Back ownership.
Programmatic anchors
Use the programmatic API for editor selections and other anchors that are not stable trigger children. Mount one PopoverOverlay in the application shell; supply a content snippet to getPopoverManager().open().
popover.open({ anchor: selectionRect, placement: "top", modal: false, ariaLabel: "Text formatting", content: formattingToolbar,});Programmatic popovers accept the same modal, dismissible, flip, and placement options. Nonmodal outside dismissal respects a newer context-menu owner and does not consume the page’s pointer event. Escape and application Back close the top contextual owner in either mode. modal controls the pointer backdrop, not a focus trap.
CSS styling
.ph-popover is the stable identification hook for Popover. Part selectors and --_ph-* properties are internal. Component CSS is scoped and unlayered; Consumer classes remain additive and utility overrides may lose precedence.
The programmatic overlay uses .ph-popover-overlay. Surfaces are portalled; do not depend on an ancestor DOM hierarchy for overrides.
Keep the shared component stylesheet and a named Theme imported. Decorative motion respects reduced-motion preferences.