# Popover

Page: /docs/components/popover

{/* Figma: Meridian → Popover (docs 48:41, component section 19:3). Spec: docs/design-system/meridian/popover.md */}

A small card anchored to its trigger: read-only context, a quick task, or a preview of an entity or record on hover. It never blocks the page and closes as soon as people move on. Popover is a product element: on the website it appears in product shots and animations, like a hover card over an entity.

```tsx
import { Button } from "@commenda/meridian/ui/button";
import { Input } from "@commenda/meridian/ui/input";
import { Popover } from "@commenda/meridian/ui/popover";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

const noop = () => {};

export function PopoverForm() {
	return (
		<Stage>
			<Popover
				trigger={<Button variant="secondary">Publish workflow</Button>}
				title="Publish workflow"
				footerConfig={{ primaryAction: { label: "Publish", onClick: noop } }}
			>
				<Input label="Version note" placeholder="e.g. Adds the Texas nexus check" />
			</Popover>
		</Stage>
	);
}
```

## Usage [#usage]

```tsx
import { Popover } from "@commenda/meridian/ui/popover";

<Popover
  mode="preview"
  trigger={<Button variant="link">Acme GmbH</Button>}
  title="Acme GmbH"
  description="Subsidiary"
>
  …key facts…
</Popover>;
```

## Form [#form]

A header with close and a footer with sm Cancel and primary, for a quick task that fits in one card. One width, 320. Opens on click.

```tsx
import { Button } from "@commenda/meridian/ui/button";
import { Input } from "@commenda/meridian/ui/input";
import { Popover } from "@commenda/meridian/ui/popover";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

const noop = () => {};

export function PopoverForm() {
	return (
		<Stage>
			<Popover
				trigger={<Button variant="secondary">Publish workflow</Button>}
				title="Publish workflow"
				footerConfig={{ primaryAction: { label: "Publish", onClick: noop } }}
			>
				<Input label="Version note" placeholder="e.g. Adds the Texas nexus check" />
			</Popover>
		</Stage>
	);
}
```

## Preview [#preview]

A read-only card on hover or focus, for something people want to check without leaving the page. Header, a hairline, key facts and at most one link. While it fetches it shows skeleton bars (loading). Hover or focus each trigger below; the last one starts loading.

```tsx
"use client";

import { Badge } from "@commenda/meridian/ui/badge";
import { Button } from "@commenda/meridian/ui/button";
import { Popover, PopoverGroup } from "@commenda/meridian/ui/popover";
import { DEFlag } from "@commenda/pathfinder/flags";
import { File02Icon } from "@commenda/pathfinder/icons/File02Icon";
import { useState } from "react";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

function Facts({ rows }: { rows: [string, string][] }) {
	return (
		<dl className="m-0 grid grid-cols-[auto_1fr] gap-x-6 gap-y-2 text-[13px]">
			{rows.map(([label, value]) => (
				<div key={label} className="contents">
					<dt className="text-(--color-text-tertiary)">{label}</dt>
					<dd className="m-0">{value}</dd>
				</div>
			))}
		</dl>
	);
}

export function PopoverPreviews() {
	const [loading, setLoading] = useState(true);
	return (
		<Stage>
			<PopoverGroup>
				<Labelled label="entity">
					<Popover
						mode="preview"
						trigger={
							<Button variant="link" leadingIcon={<DEFlag size={16} />}>
								Acme GmbH
							</Button>
						}
						title="Acme GmbH"
						description="Subsidiary"
					>
						<div className="flex flex-col gap-3">
							<Badge label="Active" tone="success" />
							<Facts
								rows={[
									["Entity type", "GmbH"],
									["Tax ID", "DE 312 845 019"],
									["Fiscal year end", "31 December"],
								]}
							/>
							<div className="flex justify-end">
								<Button variant="secondary">Open entity</Button>
							</div>
						</div>
					</Popover>
				</Labelled>
				<Labelled label="record">
					<Popover
						mode="preview"
						trigger={
							<Button variant="link" leadingIcon={<File02Icon />}>
								Delaware annual report
							</Button>
						}
						title="Delaware annual report"
						description="Filing · Acme Inc. · 2026"
					>
						<div className="flex flex-col gap-3">
							<Badge label="Due soon" tone="warning" />
							<Facts
								rows={[
									["Status", "Not started"],
									["Due", "1 March 2027"],
									["Assignee", "Priya Singh"],
									["Jurisdiction", "Delaware"],
								]}
							/>
							<div className="flex justify-end">
								<Button variant="secondary">Open filing</Button>
							</div>
						</div>
					</Popover>
				</Labelled>
				<Labelled label="loading">
					<Popover
						mode="preview"
						trigger={
							<Button variant="link" onClick={() => setLoading((l) => !l)}>
								Acme Inc.
							</Button>
						}
						title="Acme Inc."
						loadingConfig={{ isLoading: loading, label: "Loading entity" }}
					>
						<Facts rows={[["Entity type", "Corporation"]]} />
					</Popover>
				</Labelled>
			</PopoverGroup>
		</Stage>
	);
}
```

## Kinds [#kinds]

Four previews cover every hover card: entity, record, file and person. Pick by what is being previewed, not by where it appears.

## Anatomy [#anatomy]

Width 320, 16 padding, Elevation/menu. Preview: header with a 24 leading (flag or icon; a person’s avatar is 32), title Label/13 Strong and meta, a 0.5 hairline, then label and value rows 8 apart, and at most one link. Anchored 4 from the trigger.

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `trigger` (required) | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  |
| `title` (required) | `string` |  |
| `children` (required) | `ReactNode` |  |
| `open` (conditional) | `boolean` |  |
| `onOpenChange` (conditional) | `(open: boolean) => void` |  |
| `defaultOpen` | `boolean` |  |
| `description` | `ReactNode` |  |
| `positionConfig` | `{ side?: "top" \| "right" \| "bottom" \| "left"; align?: "start" \| "center" \| "end"; }` |  |
| `className` | `string` |  |
| `mode` (conditional) | `"form" \| "preview"` |  |
| `closeConfig` | `{ visible?: boolean; label?: string; }` |  |
| `footerConfig` | `OverlayFooterConfig` |  |
| `focusConfig` | `OverlayFocusConfig` |  |
| `loadingConfig` | `{ isLoading: boolean; label?: string; }` |  |

**`positionConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `side` | `"top" \| "bottom" \| "right" \| "left"` |  |
| `align` | `"center" \| "start" \| "end"` |  |

**`closeConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `visible` | `boolean` |  |
| `label` | `string` |  |

**`footerConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `primaryAction` | `OverlayAction` |  |
| `secondaryAction` | `OverlayAction` |  |
| `leadingContent` | `ReactNode` |  |
| `cancelLabel` | `string` |  |

**`focusConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `initialFocusRef` | `RefObject<HTMLElement \| null>` |  |
| `returnFocusRef` | `RefObject<HTMLElement \| null>` |  |

**`loadingConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `isLoading` (required) | `boolean` |  |
| `label` | `string` |  |

## Best practices [#best-practices]

- Use a Popover for secondary content or a quick task. A list of actions is a Dropdown; a hint on hover is a Tooltip; a task that needs focus is a Dialog.
- Form opens on click. Only preview opens on hover (or focus), after 150 ms, and it stays read-only: never a form, at most one link.
- Anchor 4 from the trigger and align to its start or end edge. Grow from the trigger corner, never from the center.
- In an animation it grows from 0.97 to 1 over 150 ms, ease-out, and closes in 100 ms. No backdrop.
- Keep a form popover to one or two fields. More than that is a Sheet or a Dialog.
- One popover at a time. Opening another closes the first.
- Source: Pathfinder Popover. Meridian keeps it as is; the two prototypes are not carried over.
