Skip to content

Popover

A non-modal floating card anchored to a trigger (positioned with Floating UI; flip/shift; outside-press + focus-leave dismissal). One fully customizable card, two opening contracts:

  • trigger="click" (default) — an intentional opening: a Button opens the panel and focus moves in; Escape returns it to the trigger.
  • trigger="hover" — a preview (the pattern elsewhere called “hover card”): the card opens on hover and keyboard focus of the slotted trigger (typically a link), with openDelay/closeDelay; focus never moves in, and the card holds nothing focusable. Hover does not exist on touch: the first click/tap opens the preview instead of activating the trigger, and once open the default action proceeds (the second tap follows the link). Content must be supplementary: never put essential information only here, because a preview is not guaranteed to every input modality. Interactive content belongs to trigger="click".

For a plain text hint, use Tooltip: different job, different role (role="tooltip" wired via aria-describedby).

<script>
import Popover from "@invisible-ui/svelte/Popover.svelte";
</script>

In Elements, a child marked slot="trigger" is the trigger and the other children are the card. Set trigger="hover" for the preview. open-change reports what the user does; setting open reports nothing:

<ds-popover label="Quick settings">
<span slot="trigger">Settings</span>
<p>Choose how the list looks.</p>
<button type="button">Compact rows</button>
</ds-popover>
<script type="module">
import "@invisible-ui/elements/define";
const popover = document.querySelector("ds-popover");
popover.addEventListener("open-change", (event) => save(event.detail.open));
</script>

In React, triggerContent is the trigger’s content (or, with trigger="hover", the trigger element itself) and children is the card. onOpenChange reports what the user does; a changed open reports nothing:

<Popover label="Quick settings" triggerContent="Settings">
<p>Choose how the list looks.</p>
<button type="button">Compact rows</button>
</Popover>
<Popover trigger="hover" triggerContent={<a href="/people/ada">@ada</a>}>
Ada Lovelace, mathematician.
</Popover>
PropTypeDefaultDescription
trigger"click" | "hover""click"Opening contract: an intentional click, or a hover/focus preview.
triggerVariant"default" | "primary" | "secondary" | "ghost" | "danger""default"Visual variant for the trigger Button (trigger="click" only).
openbooleanfalseInitial open state.
placementPopoverContext["placement"]"bottom"Preferred placement (Floating UI); flips when there's no room.
openDelaynumber300Delay before opening on hover, in ms (trigger="hover" only).
closeDelaynumber200Delay before closing on leave, in ms (trigger="hover" only).
labelstring | undefinedundefinedName for the panel. Defaults to being named by the trigger.
onOpenChange((open: boolean) => void) | undefinedundefinedCalled when the panel opens/closes.
triggerContentSnippet | undefinedundefinedThe trigger button's content (defaults to the i18n catalog's label), or the focusable trigger element itself in hover mode.

Snippets: triggerContent (the trigger button’s content, or the trigger element itself with trigger="hover") and children (the panel content). The snippet is not called trigger, which names the opening contract.

  • With trigger="click": the trigger carries aria-haspopup="dialog" / aria-expanded and, while open, aria-controls. The panel is the role="dialog" it advertises, named by the trigger’s own text — pass label when the trigger text is not a good name for the panel. Non-modal: focus moves into the panel on open; Escape closes and returns focus to the trigger; an outside pointer press or focus leaving the panel also closes (without stealing focus back).
  • With trigger="hover": opening on keyboard focus gives non-pointer users the same preview; focus is never moved or trapped; the card stays open while hovered (WCAG 1.4.13 hoverable) and Escape dismisses it (dismissable).
  • Positioning (flip/shift, stays attached on scroll) via @floating-ui/dom.
<!-- Interactive content: focus moves into the panel, Escape returns it. -->
<Popover>
{#snippet triggerContent()}<span>Open</span>{/snippet}
<p>Panel content goes here.</p>
<button type="button">Action</button>
</Popover>
<!-- Preview on hover/focus of a link (supplementary content only). -->
<Popover trigger="hover">
{#snippet triggerContent()}<a href="/users/ada">@ada</a>{/snippet}
<ProfileCard user="ada" />
</Popover>

Themeable via --ds-popover-*.