Dialog
One focused task that blocks the page.
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.
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
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
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.
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
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.
"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
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
| Prop | Type | Description |
|---|---|---|
titleRequired | string | From Pathfinder. |
childrenRequired | ReactNode | From Pathfinder. |
openConditional | boolean | From Pathfinder. |
onOpenChangeConditional | (open: boolean) => void | From Pathfinder. |
defaultOpen | boolean | From Pathfinder. |
trigger | ReactElement<unknown, string | JSXElementConstructor<any>> | From Pathfinder. |
description | ReactNode | From Pathfinder. |
footerConfig | OverlayFooterConfigView fields | From Pathfinder. |
dismissConfig | OverlayDismissConfigView fields | From Pathfinder. |
closeConfig | ObjectView fields | Hides only the header button; Escape/outside dismissal still follows dismissConfig. |
focusConfig | OverlayFocusConfigView fields | From Pathfinder. |
className | string | From Pathfinder. |
size | "md" | "lg" | "xl" | "sm" | From Pathfinder. |
dismissConfigObject fields
| Field | Type | Description |
|---|---|---|
outsidePress | boolean | |
beforeClose | (reason: OverlayCloseReason) => boolean | Promise<boolean> | |
onError | (error: unknown) => void |
closeConfigObject fields
| Field | Type | Description |
|---|---|---|
visible | boolean | |
label | string |
focusConfigObject fields
| Field | Type | Description |
|---|---|---|
initialFocusRef | RefObject<HTMLElement | null> | |
returnFocusRef | RefObject<HTMLElement | null> |
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.