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; disable Escape and backdrop close only with product approval
Stacked	Secondary confirmation on top of the first	Keep depth shallow; each layer must add clarity, not noise

Composition

Every modal renders three slots: a header with a title and close control, a body that holds the task, and a footer with the action cluster. The footer follows a trailing-primary convention across the product: secondary action on the left, primary on the right. 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") and never relies on the close icon alone. 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. Default behavior closes the modal. For destructive confirmations and unsaved-work prompts, disable casual dismiss so the operator has to make an explicit choice.
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 modal a stable id when analytics, focus, or tests need to distinguish one from another.

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.
Put a destructive action on a modal that can be dismissed by clicking outside—pair destructive verbs with explicit confirmation.
Animate open/close so slowly that operators perceive the UI as stuck.

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