Popover
A small card anchored to its trigger.
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.
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
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
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.
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
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.
"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
Four previews cover every hover card: entity, record, file and person. Pick by what is being previewed, not by where it appears.
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
| Prop | Type | Description |
|---|---|---|
triggerRequired | ReactElement<unknown, string | JSXElementConstructor<any>> | From Pathfinder. |
titleRequired | string | From Pathfinder. |
childrenRequired | ReactNode | From Pathfinder. |
openConditional | boolean | From Pathfinder. |
onOpenChangeConditional | (open: boolean) => void | From Pathfinder. |
defaultOpen | boolean | From Pathfinder. |
description | ReactNode | From Pathfinder. |
positionConfig | ObjectView fields | From Pathfinder. |
className | string | From Pathfinder. |
modeConditional | "form" | "preview" | From Pathfinder. |
closeConfig | ObjectView fields | From Pathfinder. |
footerConfig | OverlayFooterConfigView fields | From Pathfinder. |
focusConfig | OverlayFocusConfigView fields | From Pathfinder. |
loadingConfig | ObjectView fields | From Pathfinder. |
positionConfigObject fields
| Field | Type | Description |
|---|---|---|
side | "top" | "bottom" | "right" | "left" | |
align | "center" | "start" | "end" |
closeConfigObject fields
| Field | Type | Description |
|---|---|---|
visible | boolean | |
label | string |
focusConfigObject fields
| Field | Type | Description |
|---|---|---|
initialFocusRef | RefObject<HTMLElement | null> | |
returnFocusRef | RefObject<HTMLElement | null> |
loadingConfigObject fields
| Field | Type | Description |
|---|---|---|
isLoadingRequired | boolean | |
label | string |
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.