Skip to main content

Storybook

Modal

A dialog overlay that focuses user attention on a task or decision. Use when an action requires explicit user confirmation. Don't use for non-critical information that can be shown inline — use Alert instead.

Figma Storybook Docs

Description

What it does

Modal interrupts the user's current flow to present a task, decision, or critical information that must be addressed before continuing.

Where it appears

Confirmation dialogs ("Delete this project?"), short data-entry forms, destructive action warnings, and content previews that don't warrant a full page.

Why it exists

Some actions require deliberate confirmation rather than immediate execution. Modal creates a bounded context where the user's full attention is on a single decision, then returns them to where they were.

Dependencies

Not for routine feedback — if no decision is required, use Alert instead. If the message is a system-level notification, use Notification Modal.

Anatomy

PartRequired?Notes
Backdrop Required Semi-transparent overlay behind the modal. Clicking it dismisses the modal unless the action is destructive or data entry is in progress.
Header Required Contains the modal title. Must be linked to the dialog via aria-labelledby.
Body content Required The main content. Keep it focused — modals are not a canvas for complex layouts.
Close button Required × button in the header. Always present unless the action is a required confirmation with no dismissal path.
Secondary action Conditional Cancel, Go back, or an alternative action. Omit when the close button already serves this role.
Primary action Required The main call to action. Use a destructive button style for irreversible actions.

Variants

Confirmation

Asking the user to confirm an action before it executes. "Publish this consultation?" Always provide a clear Cancel path.

Destructive confirmation

The action cannot be undone. Delete, remove, archive. Use a destructive/danger button style for the primary action. State explicitly what will be deleted.

Form

Short forms that logically belong in context with the triggering page. Keep them brief — if the form grows complex, use a full page instead.

Informational

Displaying content that needs focused reading — terms, previews, help content. Use sparingly; consider whether a page or drawer would serve better.

Usage guidelines

When to use

  • Confirming an irreversible or high-consequence action.
  • Collecting a small, self-contained piece of input that doesn't warrant navigating away.
  • Displaying content that requires focused attention and explicit dismissal.

When not to use

  • For feedback after an action — use Alert.
  • For complex forms or multi-step flows — use a page or wizard pattern.
  • As an entry point for navigation — don't open modals from within modals.
  • For low-stakes confirmations — avoid over-confirming routine actions. Reserve modals for genuinely important decisions.

Do / Don't

Do

Write modal titles as plain questions or statements: "Delete this project?" or "Export stakeholder data". Not "Confirmation Required".

Don't

Don't nest modals. If a modal action opens another modal, the flow needs redesigning.

Do

For destructive actions, make the consequence explicit: "This will permanently delete 47 responses and cannot be undone."

Don't

Don't make "Cancel" the primary button. The primary action should always be the most likely next step.

Related: Alert, Notification Modal

Was this page helpful?

Updated 9 September 2026