Dialog

Usage

Overview

Dialog overlays the page with a single focused task: confirm a serious action, collect required fields, or surface information the operator must not miss. It demands attention and temporarily suspends the background. The mental model is "stop, decide, continue"—and the component earns its weight only when the alternative is silent data loss or a mis-sent decision. Overuse trains users to dismiss without reading, so a dispatch console should have few modals, and each one should be consequential.

Start a new chatroom?

Opening a chatroom pulls the current call's CAD context and notifies the on-call supervisor.

When to use

For destructive or irreversible operations

Deleting an incident record, removing a user from an agency, revoking an integration token—anything that cannot be silently undone belongs in a modal. The friction is the point. The title names the consequence ("Remove responder from incident?"), the body lists the side effects, and the primary button repeats the verb ("Remove").

For blocking validation or required input

When the user can't safely continue without making a decision—assigning an AQA review, selecting a target agency for a transferred call, confirming a license expansion—a modal holds the context still until the required input is collected. Treat the modal as the smallest possible form that captures the decision; longer workflows belong in TakeoverModal or a dedicated page.

For acknowledgments that outlive a toast

If a message must persist until the operator explicitly acknowledges it (license warnings, on-call handoffs, training debriefs), a modal is the right weight. A dismissible Snackbar or inline Banner lets the user miss it; a modal guarantees a click.

When not to use

For help, filters, or secondary context

Non-blocking help, inline filters, and contextual summaries belong in Popover or inline expansion. Forcing them into a modal interrupts the flow and trains operators to dismiss modals reflexively.

For multi-step or reference-heavy workflows

When users need to keep a data table, incident, or transcript visible while they work, use Drawer (anchored side panel) or TakeoverModal (full-screen workflow). A modal hides the context behind a backdrop; long flows feel airless inside one.

For ambient notifications

Background-sync toasts, save-succeeded confirmations, and other disposable outcomes belong in Snackbar. Modals should not announce routine events.

For purely informational content that fits on the page

If the content could live inline (policy notes, read-only detail), a modal adds weight without adding clarity. Ask whether the user needs a blocking moment or just information—if it's the latter, a Banner or static section is better.

Variants

Shape	Purpose	Emphasis
Standard confirm / form	Single decision or short form	One primary action, explicit cancel
Destructive primary	Irreversible operations	Destructive type on the primary button; body lists impacts
Non-dismissible	Required user choice	Rare; veto Escape with `details.cancel()` only with product approval. A backdrop press never closes a Dialog
Stacked	Secondary confirmation on top of the first	Keep depth shallow; each layer must add clarity, not noise

Composition

Every dialog has three regions. DialogContent renders the header: the title (an h2) and an optional description. There is no close button in the header; compose DialogClose in the footer. DialogBody holds the task. DialogFooter holds the actions, aligned to the inline end; put the primary action last. When an action is destructive, the primary button uses the destructive type so its styling matches its consequence.

Title

Specific, not generic. "Remove responder from incident?" rather than "Are you sure?" The title is the accessible name for the dialog; it should read sensibly without the body.

Body

Short, scannable. Use bullets for lists of impacts and keep the body under one visual beat. If the consequence lives in paragraph five of a wall of copy, nobody will read it—pull it up.

Primary button names the outcome ("Remove", "Save", "Confirm transfer"). Cancel is explicit ("Cancel", "Keep editing"): a Button inside DialogClose, because the dialog has no close icon. Match the button type to the action: destructive primaries for destructive verbs, primary for commits, secondary for de-emphasized alternates.

Content guidelines

Run every string through formatMessage; test the longest expected translation inside the modal's width before shipping.
Titles describe the decision, not the mechanic. "Save changes before leaving?" describes the decision; "Unsaved changes" describes the state.
Body copy states impacts in the same voice across the product. Consistent verbs reduce cognitive load in a dispatch console where operators see dozens of modals a day.
Error recovery lives inside the modal. Keep the modal open, surface the error near the offending field, and let the operator fix it without losing progress.

Behavior and states

Focus trap. Focus moves into the modal on open and is trapped there until dismiss; on close, focus returns to the trigger element.
Escape and backdrop. A press on the backdrop does not close a Dialog. Escape (or the platform back gesture) requests a close and reports close-request to onOpenChange; call details.cancel() on a cancelable request to keep the dialog open, for example while a form has unsaved changes. A forced close, such as a repeated Escape the browser does not let the page block, is not cancelable and is still reported once.
Loading. Disable repeated submits on the primary button; show in-button progress for slow requests rather than a separate loading UI.
Errors. Inline field errors for forms; for server failures, keep the modal open and show a persistent error above the footer so the retry affordance stays in the action cluster.

Best practices

Align the primary action to the trailing edge of the footer. Destructive primaries still use destructive styling—the emphasis follows the verb, not the side.
Lazy-load heavy modal bodies. The modal should feel immediate; the content can resolve inside it.
Give each dialog a specific title. Tests find a dialog by role (dialog or alertdialog) and name; the dialog takes no id prop.

Don't

Stack more than two modals. Depth beyond that is almost always a navigation problem wearing a dialog costume.
Open a second modal for information that could be a paragraph in the first.
Animate open/close so slowly that operators perceive the UI as stuck.

In a Module Federation shell

The shell provides what a dialog needs from the page, once: its entry imports @prepared911/ui/styles.css, it sets data-theme on the document element, and it renders DesignSystemEnvironment for the locale and time zone (see remote composition). A dialog needs no provider, portal root, or z-index. DialogContent is a native <dialog> opened with showModal(), so it paints in the top layer above the shell's chrome, a slot's overflow, transform, or z-index cannot clip or cover it, and the page behind it does not scroll. It renders in place, so it takes the theme of the nearest data-theme region around its trigger. DialogTrigger clones its child, so a RemoteComponent mount cannot be the trigger. A remote uses a dialog in one of two ways:

The remote renders the whole Dialog, trigger included, imported from @prepared911/ui/dialog. It imports no @prepared911/ui stylesheet; the shell's covers it.
The shell owns the Dialog and its trigger, and a RemoteComponent fills the content slot:

Either way, focus moves into the dialog and Tab stays there, and Escape closes it and returns focus to the trigger, in the shell or in the remote.

Accessibility

Focus management, dialog semantics, Escape handling, and screen reader announcements carry real operational weight—see Accessibility for the component-vs-app contract, runnable focus examples, and the open/close announcement pattern.

Drawer for side-anchored detail panels that preserve context.
Dialog for a focused edit.
Takeover dialog for a task that needs the full viewport.
Popover for non-blocking secondary context.
Banner for inline messaging that doesn't need a blocking moment.
Button for primary action styling inside the footer.

Metric Card / Accessibility

Modal / API and Development