# Dialog

Page: /docs/components/dialog

{/* Figma: Meridian → Dialog (docs 46:110, component section 22:2). Spec: docs/design-system/meridian/dialog.md */}

Blocks the page for one focused task: a short form, a choice, a confirmation. Dialog is a product element: on the website it appears in product shots and animations of the Commenda app, not as a marketing pop-up. If people need the page behind it, use a Sheet.

```tsx
import { Button } from "@commenda/meridian/ui/button";
import { Dialog } from "@commenda/meridian/ui/dialog";
import { Input } from "@commenda/meridian/ui/input";
import { Select } from "@commenda/meridian/ui/select";
import { DEFlag, USFlag } from "@commenda/pathfinder/flags";
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>
	);
}

const noop = () => {};

function EntityForm() {
	return (
		<div className="flex flex-col gap-4">
			<Input label="Legal name" defaultValue="Acme GmbH" />
			<Select
				label="Country"
				defaultValue="DE"
				options={[
					{ value: "DE", label: "Germany", leadingIcon: <DEFlag size={16} /> },
					{ value: "US", label: "United States", leadingIcon: <USFlag size={16} /> },
				]}
			/>
		</div>
	);
}

export function DialogSizes() {
	return (
		<Stage>
			{(["sm", "md", "lg", "xl"] as const).map((size) => (
				<Labelled
					key={size}
					label={{ sm: "sm · 400", md: "md · 480", lg: "lg · 600", xl: "xl · 800" }[size]}
				>
					<Dialog
						size={size}
						trigger={<Button variant="secondary">Open {size}</Button>}
						title="Edit entity details"
						description="Changes apply to filings created from today."
						footerConfig={{
							primaryAction: { label: "Save changes", onClick: noop },
							// lg shows the one tertiary action, on the left of the footer.
							leadingContent:
								size === "lg" ? <Button variant="link">Save as draft</Button> : undefined,
						}}
					>
						<EntityForm />
					</Dialog>
				</Labelled>
			))}
		</Stage>
	);
}
```

## Usage [#usage]

```tsx
import { Dialog } from "@commenda/meridian/ui/dialog";

<Dialog
  trigger={<Button variant="secondary">Edit</Button>}
  title="Edit entity details"
  description="Changes apply to filings created from today."
  footerConfig={{ primaryAction: { label: "Save changes", onClick: save } }}
>
  <Input label="Legal name" />
</Dialog>;
```

## Sizes [#sizes]

sm 400 for confirms, md 480 for one or two fields, lg 600 for forms (the default), xl 800 for tables and previews. The body scrolls on its own; the header and footer hairlines appear only once it does. The footer can carry one tertiary action on the left. Open each size below.

```tsx
import { Button } from "@commenda/meridian/ui/button";
import { Dialog } from "@commenda/meridian/ui/dialog";
import { Input } from "@commenda/meridian/ui/input";
import { Select } from "@commenda/meridian/ui/select";
import { DEFlag, USFlag } from "@commenda/pathfinder/flags";
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>
	);
}

const noop = () => {};

function EntityForm() {
	return (
		<div className="flex flex-col gap-4">
			<Input label="Legal name" defaultValue="Acme GmbH" />
			<Select
				label="Country"
				defaultValue="DE"
				options={[
					{ value: "DE", label: "Germany", leadingIcon: <DEFlag size={16} /> },
					{ value: "US", label: "United States", leadingIcon: <USFlag size={16} /> },
				]}
			/>
		</div>
	);
}

export function DialogSizes() {
	return (
		<Stage>
			{(["sm", "md", "lg", "xl"] as const).map((size) => (
				<Labelled
					key={size}
					label={{ sm: "sm · 400", md: "md · 480", lg: "lg · 600", xl: "xl · 800" }[size]}
				>
					<Dialog
						size={size}
						trigger={<Button variant="secondary">Open {size}</Button>}
						title="Edit entity details"
						description="Changes apply to filings created from today."
						footerConfig={{
							primaryAction: { label: "Save changes", onClick: noop },
							// lg shows the one tertiary action, on the left of the footer.
							leadingContent:
								size === "lg" ? <Button variant="link">Save as draft</Button> : undefined,
						}}
					>
						<EntityForm />
					</Dialog>
				</Labelled>
			))}
		</Stage>
	);
}
```

## Confirm [#confirm]

A preset for one yes-or-no decision: a question, one line on what happens, and a primary named for the action. No close button and no body. Destructive uses the destructive primary. The second example shows loading while it works.

```tsx
"use client";

import { Button } from "@commenda/meridian/ui/button";
import { ConfirmDialog } from "@commenda/meridian/ui/dialog";
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>
	);
}

const noop = () => {};

export function DialogConfirm() {
	const [loading, setLoading] = useState(false);
	return (
		<Stage>
			<Labelled label="default">
				<ConfirmDialog
					trigger={<Button>Submit report</Button>}
					title="Submit the annual report?"
					description="We’ll file it with Delaware and pay the franchise tax from the account ending 4412."
					confirmAction={{ label: "Submit report", onClick: noop }}
				/>
			</Labelled>
			<Labelled label="destructive · loading">
				<ConfirmDialog
					trigger={<Button variant="secondary">Delete policy</Button>}
					title="Delete this policy?"
					description="Contract R&D services and its 3 versions will be removed. This can’t be undone."
					confirmAction={{
						label: "Delete policy",
						destructive: true,
						loadingConfig: { isLoading: loading },
						onClick: () => {
							setLoading(true);
							setTimeout(() => setLoading(false), 1500);
						},
					}}
				/>
			</Labelled>
		</Stage>
	);
}
```

## Anatomy [#anatomy]

Header: title with an optional description and the close IconButton (sm). Body: 24 side padding, scrolls on its own. Footer: Cancel and the primary right-aligned, 8 apart, one tertiary action on the left. Radius 12, Elevation/modal, on a soft-pearl 1000 backdrop at 40%.

| Size | Width |
| --- | --- |
| `sm` | 400 |
| `md` | 480 |
| `lg` | 600 |
| `xl` | 800 |

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `title` (required) | `string` |  |
| `children` (required) | `ReactNode` |  |
| `open` (conditional) | `boolean` |  |
| `onOpenChange` (conditional) | `(open: boolean) => void` |  |
| `defaultOpen` | `boolean` |  |
| `trigger` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  |
| `description` | `ReactNode` |  |
| `footerConfig` | `OverlayFooterConfig` |  |
| `dismissConfig` | `OverlayDismissConfig` |  |
| `closeConfig` | `{ visible?: boolean; label?: string; }` | Hides only the header button; Escape/outside dismissal still follows dismissConfig. |
| `focusConfig` | `OverlayFocusConfig` |  |
| `className` | `string` |  |
| `size` | `"md" \| "lg" \| "xl" \| "sm"` |  |

**`footerConfig` fields**

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

**`dismissConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `outsidePress` | `boolean` |  |
| `beforeClose` | `(reason: OverlayCloseReason) => boolean \| Promise<boolean>` |  |
| `onError` | `(error: unknown) => void` |  |

**`closeConfig` fields**

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

**`focusConfig` fields**

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

## Best practices [#best-practices]

- One task, one step. Multi-step flows are full pages, never a dialog. If people need the page behind it, use a Sheet.
- The title says the task (Edit entity details) or asks the question (Delete this policy?). Sentence case.
- Name the primary for what it does: Save changes, Delete policy. Never OK or Yes.
- Cancel sits left of the primary, both right-aligned. At most one tertiary action goes on the left.
- In an animation, the backdrop fades in and the dialog grows from 0.97 over 200 ms, ease-out. It closes in 150 ms.
- Never use a Dialog as a marketing pop-up or to gate content. Lead capture lives on the page.
- Source: Pathfinder Dialog. Meridian keeps it as is; the prototype is not carried over.
