Skip to content
Statix Design System

Overlays

Popover

A small card anchored to a button. Use it for extra details or a quick setting that does not need its own page.

import * as Popover from '@statix/ui/popover';

Playground

Controls
<Popover.Root>
	<Popover.Trigger>
		{#snippet child({ props })}
			<Button variant="outline" {...props}>Backup details</Button>
		{/snippet}
	</Popover.Trigger>
	<Popover.Content>
		<Popover.Header>
			<Popover.Title>Last backup today at 03:10</Popover.Title>
			<Popover.Description>yoga-berger.de, 1.2 GB, kept for 30 days.</Popover.Description>
		</Popover.Header>
	</Popover.Content>
</Popover.Root>

Examples

Basic

A title and a short explanation. Popover.Header stacks them with a 4px gap.

<script lang="ts">
	import * as Popover from '@statix/ui/popover';
	import { Button } from '@statix/ui/button';
	import CircleHelpIcon from '@lucide/svelte/icons/circle-help';
</script>

<Popover.Root>
	<Popover.Trigger>
		{#snippet child({ props })}
			<Button variant="ghost" size="sm" {...props}>
				<CircleHelpIcon data-icon="inline-start" />
				What is a staging site?
			</Button>
		{/snippet}
	</Popover.Trigger>
	<Popover.Content>
		<Popover.Header>
			<Popover.Title>Staging site</Popover.Title>
			<Popover.Description>
				A private copy of yoga-berger.de. Try changes there first, then publish them with one click.
			</Popover.Description>
		</Popover.Header>
	</Popover.Content>
</Popover.Root>

Backup details

Details behind a status button, with a follow-up action. Fields inside the popover use the bg-2 fill and rounded-sm.

<script lang="ts">
	import * as Popover from '@statix/ui/popover';
	import { Button } from '@statix/ui/button';
	import CircleCheckIcon from '@lucide/svelte/icons/circle-check';
	import RotateCcwIcon from '@lucide/svelte/icons/rotate-ccw';

	const details = [
		{ label: 'Size', value: '1.2 GB' },
		{ label: 'Contains', value: 'Files, database, settings' },
		{ label: 'Kept until', value: '18 December 2026' }
	];
</script>

<Popover.Root>
	<Popover.Trigger>
		{#snippet child({ props })}
			<Button variant="outline" {...props}>
				<CircleCheckIcon data-icon="inline-start" class="text-success" />
				Last backup today at 03:10
			</Button>
		{/snippet}
	</Popover.Trigger>
	<Popover.Content class="w-80" align="start">
		<Popover.Header>
			<Popover.Title>Backup from today, 03:10</Popover.Title>
			<Popover.Description>yoga-berger.de, created automatically</Popover.Description>
		</Popover.Header>
		<dl class="grid gap-2 rounded-sm bg-secondary p-3 text-small">
			{#each details as item (item.label)}
				<div class="flex justify-between gap-4">
					<dt class="text-ink-2">{item.label}</dt>
					<dd class="text-right font-medium text-ink">{item.value}</dd>
				</div>
			{/each}
		</dl>
		<Button size="sm" variant="dark">
			<RotateCcwIcon data-icon="inline-start" />
			Restore this backup
		</Button>
	</Popover.Content>
</Popover.Root>

With a form

A one-field setting. Bind open to close the popover after saving. Focus moves to the first field on open.

<script lang="ts">
	import * as Popover from '@statix/ui/popover';
	import { Button } from '@statix/ui/button';
	import { Input } from '@statix/ui/input';
	import { Label } from '@statix/ui/label';
	import ForwardIcon from '@lucide/svelte/icons/forward';

	let open = $state(false);
</script>

<Popover.Root bind:open>
	<Popover.Trigger>
		{#snippet child({ props })}
			<Button variant="secondary" {...props}>
				<ForwardIcon data-icon="inline-start" />
				Forward emails
			</Button>
		{/snippet}
	</Popover.Trigger>
	<Popover.Content>
		<Popover.Header>
			<Popover.Title>Forward info@yoga-berger.de</Popover.Title>
			<Popover.Description>We send a copy of every new email to this address.</Popover.Description>
		</Popover.Header>
		<form
			class="grid gap-3"
			onsubmit={(event) => {
				event.preventDefault();
				open = false;
			}}
		>
			<div class="grid gap-2">
				<Label for="forward-to">Forward to</Label>
				<Input id="forward-to" type="email" placeholder="anna@example.com" />
			</div>
			<div class="flex justify-end gap-2">
				<Popover.Close>
					{#snippet child({ props })}
						<Button variant="ghost" size="sm" {...props}>Cancel</Button>
					{/snippet}
				</Popover.Close>
				<Button type="submit" size="sm">Save</Button>
			</div>
		</form>
	</Popover.Content>
</Popover.Root>

Guidelines

Do

  • Keep it short: a title, two lines of text and at most one action.
  • Use a popover when the content needs buttons or links. For a plain label use Tooltip.

Don't

  • Don’t put a long form or a table in a popover. Use a Sheet or a page.
  • Don’t open a popover on hover. It opens on click or tap.

Accessibility

  • The trigger gets aria-expanded and aria-controls. The content has role="dialog".
  • Focus moves into the popover on open and back to the trigger on close.
  • Escape and a click outside close it.
  • Popover.Title and Popover.Description are plain divs. Add aria-labelledby on Popover.Content if screen readers should announce the title.

API reference

Popover.Root

Holds the open state. Renders no element.

PropTypeDefault
open bindboolean

Whether the popover is open.

false
onOpenChange (open: boolean) => void

Called when the popover opens or closes.

–

Popover.Trigger

renders <button> and accepts its attributes

Toggles the popover. Use the child snippet to render a Button.

Data attributeMeaning
data-state"open" or "closed".

Popover.Content

renders <div> and accepts its attributes

The card: 288px wide, white, 16px radius, hairline border and overlay shadow.

PropTypeDefault
side 'top' | 'right' | 'bottom' | 'left'

Preferred side. It flips when there is no room.

'bottom'
align 'start' | 'center' | 'end'

Alignment against the trigger.

'center'
sideOffset number

Gap to the trigger in pixels.

8
portalProps Popover.PortalProps

Props for the portal.

–
ref bindHTMLDivElement | null

The content element.

–
class ClassValue

Merged with the card classes, for example w-80.

–
Data attributeMeaning
data-slot="popover-content"Always present.
data-sideThe side it ended up on.
data-state"open" or "closed".

Popover.Header

renders <div> and accepts its attributes

Stacks title and description.

Popover.Title

renders <div> and accepts its attributes

15px, medium, ink.

Popover.Description

renders <div> and accepts its attributes

13.5px in ink-2.

Popover.Close

renders <button> and accepts its attributes

Closes the popover.