Skip to content

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
basic-popover.svelte
<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
placement-options.svelte
<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
offset-flip.svelte
<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
non-dismissible-backdrop.svelte
<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
controlled-open.svelte
<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
programmatic-overlay.svelte
<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

NameTypeDefaultDescription
openbindablebooleanfalseWhether the popover is open. Bindable.
onOpenChange(open: boolean) => void—Callback when open state changes.
placementPopoverPlacement'bottom-start'Positioning relative to the trigger element.
offsetnumber4Gap in pixels between trigger and popover.
flipbooleantrueFlip to opposite side if there is not enough space.
dismissiblebooleantrueClose on an outside pointer press, including touch.
modalbooleantrueWhether a backdrop blocks interaction outside the panel. Set false for selection toolbars or other controls that keep the page interactive.
classstring''Additional CSS classes for the floating panel.
triggerSnippet<[toggle: () => void]>—Trigger region - receives toggle. Optional only if you drive open entirely from the outside (unusual).
childrenSnippet<[]>—Popover body content.

Usage tips

  • The trigger snippet receives a toggle function - call it on click to open/close.
  • Use bind:open for 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: false to 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.
  • Escape closes the top contextual owner regardless of dismissible (handled on window).

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.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.