---
title: "Popover"
description: "A floating panel anchored to an element."
category: "Overlays"
slug: popover
url: /components/popover
since: "0.2.0"
status: "stable"
---

# Popover

A floating panel anchored to an element.

## Import

```svelte
import { Popover } from '@elluzion/iv-ui';
```

## Preview

Click the trigger to toggle the panel; Escape or an outside click closes it.

```svelte
<script lang="ts">
	import { Button, Popover } from '@elluzion/iv-ui';

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

<div class="stack">
	<div>
		<Button id="popover-click-trigger" variant="outline">Filters</Button>
	</div>
	<Popover bind:open anchor="#popover-click-trigger" placement="bottom" align="start">
		<div class="panel">
			<p class="title">Active filters</p>
			<p class="body">Branch: main · Status: failed · Author: any</p>
		</div>
	</Popover>
</div>

<style>
	.stack {
		display: flex;
		justify-content: center;
	}

	.panel {
		padding: var(--iv_spacing-md);
		max-width: 260px;
	}

	.title {
		margin: 0 0 var(--iv_spacing-xs);
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground);
	}

	.body {
		margin: 0;
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground-dim);
	}
</style>
```

## Usage

- `anchor` takes an element or a selector; the panel is positioned against it.
- `showOn` and `hideOn` choose the trigger events; combine `hover` with `interactive` to keep the panel open while hovered.
- Bind `open` to control the panel from your own state.

## Examples

### Hover

Open on hover or focus and keep the panel interactive.

```svelte
<script lang="ts">
	import { Button, Popover } from '@elluzion/iv-ui';
</script>

<div class="stack">
	<div>
		<Button id="popover-hover-trigger" variant="ghost">Hover or focus me</Button>
	</div>
	<Popover
		anchor="#popover-hover-trigger"
		placement="top"
		showOn={['hover', 'focus']}
		hideOn={['hover', 'blur']}
		interactive
	>
		<p class="body">The panel stays open while the pointer is inside it.</p>
	</Popover>
</div>

<style>
	.stack {
		display: flex;
		justify-content: center;
	}

	.body {
		margin: 0;
		padding: var(--iv_spacing-sm) var(--iv_spacing-md);
		max-width: 240px;
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground-dim);
	}
</style>
```

### Placement

Change the preferred side; the panel flips when space runs out.

```svelte
<script lang="ts">
	import type { PopoverPlacement } from '@elluzion/iv-ui';
	import { Button, Popover } from '@elluzion/iv-ui';

	let open = $state(false);
	let placement = $state<PopoverPlacement>('bottom');
</script>

<div class="stack">
	<div class="row">
		{#each ['top', 'bottom', 'left', 'right'] as side (side)}
			<Button
				size="sm"
				variant={placement === side ? 'primary' : 'outline'}
				onclick={() => (placement = side as PopoverPlacement)}
			>
				{side}
			</Button>
		{/each}
	</div>
	<div>
		<Button id="popover-placement-trigger" variant="ghost">Toggle panel</Button>
	</div>
	<Popover bind:open anchor="#popover-placement-trigger" {placement} closeOnOutside={false}>
		<p class="body">Preferred side: {placement}. The panel flips when space runs out.</p>
	</Popover>
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		align-items: center;
		gap: var(--iv_spacing-md);
	}

	.row {
		display: flex;
		flex-wrap: wrap;
		justify-content: center;
		gap: var(--iv_spacing-xs);
	}

	.body {
		margin: 0;
		padding: var(--iv_spacing-sm) var(--iv_spacing-md);
		max-width: 220px;
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground-dim);
	}
</style>
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` **bindable** | `boolean` | `false` | Whether the popover is open. Bind with `bind:open`. |
| `anchor` | `string \| HTMLElement \| null` | `null` | Element or selector the popover is positioned against. |
| `placement` | `PopoverPlacement` | `'bottom'` | Preferred side of the anchor. |
| `align` | `PopoverAlign` | `'center'` | Alignment along the chosen side. |
| `gap` | `number` | `8` | Distance from the anchor in pixels. |
| `closeOnOutside` | `boolean` | `true` | Closes when a click lands outside the popover. |
| `closeOnEscape` | `boolean` | `true` | Closes on Escape. |
| `interactive` | `boolean` | `true` | Keeps the popover open while it is hovered or focused. |
| `showOn` | `PopoverShowEvent[]` | `['click']` | Events that open the popover. |
| `hideOn` | `PopoverHideEvent[]` | `['click']` | Events that close the popover. |
| `className` | `string` | `''` | Extra classes merged onto the root element. |

### Events

| Event | Handler type | Description |
| --- | --- | --- |
| `open` | `() => void` | Called after the popover opens. |
| `close` | `() => void` | Called after the popover closes. |
| `click` | `(e: MouseEvent) => void` | Called when the element is activated. |

The legacy `on:name` form is accepted for every event.

### Snippets

| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Content rendered inside the component. |

### Types

#### `PopoverPlacement`

Side of the anchor the popover prefers.

```ts
type PopoverPlacement = 'top' | 'bottom' | 'left' | 'right';
```

#### `PopoverAlign`

Alignment along the popover edge.

```ts
type PopoverAlign = 'start' | 'center' | 'end';
```

#### `PopoverShowEvent`

Events that can open a popover.

```ts
type PopoverShowEvent = 'click' | 'hover' | 'focus';
```

#### `PopoverHideEvent`

Events that can close a popover.

```ts
type PopoverHideEvent = 'click' | 'hover' | 'blur';
```

### Tokens used

`--iv_border` · `--iv_font-mono` · `--iv_popover-max-w` · `--iv_popover-min-w` · `--iv_radius-sm` · `--iv_shadow-md` · `--iv_surface-raised` · `--iv_z-dropdown`

See the [token reference](/foundations/tokens.md) for values.

### CSS hooks

`.iv-panel` · `.iv-root`

## Accessibility

| Keys | Action |
| --- | --- |
| `Enter / Space` | Toggles a click-triggered popover. |
| `Escape` | Closes the popover. |

- The anchor receives `aria-haspopup`, `aria-expanded`, and `aria-controls` while the panel is open.
- An interactive panel uses `role="dialog"` with `aria-modal="false"`.
- The panel is clamped to the viewport and repositioned on scroll and resize.

## Related

- [Tooltip](/components/tooltip.md)
- [Menu](/components/menu.md)
- [Dialog](/components/dialog.md)
- [ContextMenu](/components/context-menu.md)