Skip to content

Popover

A popover: a non-modal panel anchored to a trigger. Render Popover.Trigger and Popover.Content inside it. The page stays interactive while it is open.

Built on bits-ui Popover.

<Popover bind:open>
<Popover.Trigger class="button">Open</Popover.Trigger>
<Popover.Content>
<p>Details</p>
<Popover.Close />
</Popover.Content>
</Popover>
  • Composed from parts, so the trigger, the panel, and the close button are yours to arrange.
  • open is bindable, two-way or as a getter and setter. State & binding explains both modes.
  • Non-modal: the page stays interactive while the panel is open.
  • The panel floats in a portal, positioned to the trigger, and flips to the other side when there is no room.
  • Closes on Escape and on a press outside, and returns focus to the trigger.

Every part is a property on Popover. Popover renders no element. Popover.Content portals itself to the body. The panel is a dialog, so give Popover.Content an aria-label or aria-labelledby.

<Popover>
<Popover.Trigger />
<Popover.Content aria-label="Details">
...
<Popover.Close />
</Popover.Content>
</Popover>

bind:open on the root.

open: false

Code
TwoWay.svelte
<script lang="ts">
import { Popover } from "@viamrobotics/prime-ui";
let open = $state(false);
</script>
<div class="not-content">
<Popover bind:open>
<Popover.Trigger class="button">Details</Popover.Trigger>
<Popover.Content aria-label="Details">
<p class="text-sm">Two-way bound to <code>open</code>.</p>
</Popover.Content>
</Popover>
<p class="mt-3 text-sm text-subtle-2">open: <code>{open}</code></p>
</div>

Pass bind:open a getter and a setter. The setter can decline a change.

Code
Controlled.svelte
<script lang="ts">
import { Popover } from "@viamrobotics/prime-ui";
let open = $state(false);
let isLocked = $state(true);
</script>
<div class="not-content flex flex-col items-start gap-3">
<label class="flex items-center gap-2 text-sm">
<input type="checkbox" bind:checked={isLocked} />
Keep closed
</label>
<Popover
bind:open={
() => open,
(next) => {
if (!isLocked) open = next;
}
}
>
<Popover.Trigger class="button">Details</Popover.Trigger>
<Popover.Content aria-label="Details">
<p class="text-sm">The setter declines every change while the box is checked.</p>
</Popover.Content>
</Popover>
</div>

Popover.Close closes the panel. It renders a close icon with aria-label="Close" by default. Pass children to replace the icon, and an aria-label if the text does not name the action.

Code
WithClose.svelte
<script lang="ts">
import { Popover } from "@viamrobotics/prime-ui";
</script>
<div class="not-content">
<Popover>
<Popover.Trigger class="button">Rename</Popover.Trigger>
<Popover.Content aria-label="Rename sensor">
<div class="flex items-center gap-2">
<input class="input" aria-label="Name" value="Arm" />
<Popover.Close class="button">Done</Popover.Close>
<Popover.Close />
</div>
</Popover.Content>
</Popover>
</div>

Popover.Content takes side and align to place the panel, and sideOffset and alignOffset to nudge it.

Code
Placed.svelte
<script lang="ts">
import { Popover } from "@viamrobotics/prime-ui";
</script>
<div class="not-content pt-32">
<Popover>
<Popover.Trigger class="button">Open above</Popover.Trigger>
<Popover.Content aria-label="Details" side="top" align="end" sideOffset={8}>
<p class="text-sm">Opens above, aligned to the trigger's end edge.</p>
</Popover.Content>
</Popover>
</div>

Text trigger

With a close button

A popover does not lock page scroll, trap focus, or make the rest of the page inert. Tab moves through the panel and on to the rest of the page. Use a dialog when the user must answer before continuing.

Every part that renders an element takes class on that element. Popover.Trigger is a real <button> with no look of its own beyond the focus ring, so add button or icon-button. Popover.Close wears icon-button while it shows its default close icon. With children it wears no class of its own, so class="button" gives a text close the button class alone. Popover renders no element, so it takes no class. bits-ui sets the data attributes below. Popover.Content wears z-popover and the shadow-popover token; see z layers.

Part Attribute Value
Trigger data-state open or closed
Content data-state open or closed
Content data-side the resolved side of the trigger
Content data-align the resolved alignment
KeyAction
Enter / SpaceOn the trigger, opens or closes the panel.
TabMoves focus within the panel, then on.
EscapeCloses the panel and focuses the trigger.
PropTypeDefaultDescription
bind:openbooleanWhether the popover is open. Two-way bindable.
childrenSnippetThe Popover.* parts.

Popover.Close

A button that closes the enclosing Popover. It renders a close icon unless given children, and wears icon-button only then.

PropTypeDefaultDescription
idstringElement id. null is not accepted.

Plus everything in HTMLButtonAttributes, spread onto the element.

Popover.Content

The floating panel of a Popover, portaled to the body. The panel is a dialog, so give it aria-label or aria-labelledby. It closes on Escape and on a press outside, and returns focus to the trigger.

PropTypeDefaultDescription
idstringElement id. null is not accepted.
dir'ltr' | 'rtl'Text direction of the panel. auto is not accepted, because positioning needs a concrete direction.
side'top' | 'right' | 'bottom' | 'left''bottom'Which side of the trigger the panel opens on.
align'start' | 'center' | 'end''center'Alignment of the panel along the trigger's edge.
sideOffsetnumber4Gap in pixels between the trigger and the panel.
alignOffsetnumber0Shift in pixels along the alignment axis.
portalPortalTargettrueWhere the panel renders: true at the end of <body>, false in place, or inside an element or the first match of a CSS selector.

Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.

Popover.Trigger

The button that toggles a Popover. Add button or icon-button to style it.

Takes extraClasses, children, ...restProps }: Props as its props.