Loading…
Overlay
Dialog
An overlay window that requires user interaction before returning to the main content.
ModalPopupLightbox
Overview
The Dialog (also called a modal) is an overlay window that appears on top of the main content, requiring user interaction before they can return to the underlying page. It demands attention — and that's exactly why you should use it sparingly.
Dialogs interrupt the user's flow. Every time you open one, you're saying: "Stop what you're doing and deal with this first." That's sometimes necessary (confirming a destructive action, collecting required input), but it's frequently overused. If the content can live inline on the page, it should.
When to use a Dialog:
- Confirming irreversible actions ("Delete this project? This cannot be undone.")
- Collecting focused input that requires context isolation (a quick form, a settings change)
- Displaying critical information that must be acknowledged before proceeding
- Previewing content (image lightbox, video player)
When NOT to use a Dialog:
- For information that isn't urgent — use an Alert or Toast instead
- For complex, multi-step forms — use a dedicated page or a Stepper
- For navigation — use a Drawer or Sidebar
- For simple confirmations — consider an inline confirmation pattern
Enhance your dialog's visual treatment with our Shadow Generator for depth, the Glassmorphism Generator for frosted-glass backdrops, and the Transition Generator for smooth open/close animations.
Variants
Common Dialog Variants
| Variant | Purpose | Typical Size |
|---|---|---|
| Alert Dialog | Confirms a user action, especially destructive ones. Has a clear cancel + confirm button pair. | Small (400–480px wide) |
| Form Dialog | Contains a short form (1–5 fields) for focused data entry. | Medium (480–560px wide) |
| Full-screen Dialog | Complex content that needs maximum space (e.g., rich text editor, image cropper). | Full viewport on mobile, max ~900px on desktop |
| Drawer-style Dialog | Slides in from the side rather than appearing centered. See Drawer. | 320–480px wide, full height |
| Nested Dialog | A dialog opened from within another dialog. Avoid if at all possible — stacking modals is a UX anti-pattern. | Same as parent |
| Non-modal Dialog | Does not block interaction with the page behind it. Think chat widgets or sticky panels. | Variable |
Size Variants
| Size | Max Width | Use Case |
|---|---|---|
| Small | 400px | Confirmations, simple alerts |
| Medium | 560px | Short forms, settings panels |
| Large | 720px | Complex content, data previews |
| Full | 100vw (with padding) | Mobile-first, image viewers |
Use the Animation Generator to craft entrance/exit animations for your dialog.
Properties
Dialog Properties
| Property | Type | Default | Description |
|---|---|---|---|
open | boolean | false | Controls whether the dialog is visible |
onClose | () => void | — | Callback when the dialog is dismissed (backdrop click, Escape key, close button) |
size | 'sm' | 'md' | 'lg' | 'full' | 'md' | Max-width of the dialog panel |
closeOnBackdropClick | boolean | true | Whether clicking the backdrop dismisses the dialog |
closeOnEscape | boolean | true | Whether pressing Escape dismisses the dialog |
initialFocus | RefObject<HTMLElement> | — | Element to focus when the dialog opens (defaults to first focusable element) |
returnFocus | boolean | true | Return focus to the trigger element on close |
role | 'dialog' | 'alertdialog' | 'dialog' | Use alertdialog for confirmations that require acknowledgment |
aria-labelledby | string | — | ID of the dialog title element |
aria-describedby | string | — | ID of the dialog description element |
preventScroll | boolean | true | Prevents body scroll when dialog is open |
Token Mappings
Design Token Mappings
| Token Category | Token Example | Dialog Usage |
|---|---|---|
| Color – Surface | --color-surface-elevated | Dialog panel background |
| Color – Backdrop | --color-overlay (rgba(0,0,0,0.5)) | Semi-transparent backdrop. Try Glassmorphism Generator for frosted glass. |
| Border Radius | --radius-xl (16px) | Dialog corners. Preview with Border Radius Generator. |
| Shadow | --shadow-2xl | Dialog elevation. Configure with Shadow Generator. |
| Spacing – Padding | --space-6 (24px) | Internal padding of the dialog body |
| Spacing – Gap | --space-4 (16px) | Gap between title, body, and footer |
| Typography | --font-size-lg, --font-weight-semibold | Dialog title styling |
| Transition | --duration-normal (200ms) | Open/close animation duration |
| Z-index | --z-modal (50) | Stacking above page content |
For a comprehensive look at token architecture, read our Design Tokens Complete Guide.
States
Dialog States
| State | Visual Behavior | Implementation |
|---|---|---|
| Closed | Not rendered or rendered with display: none. No DOM presence is ideal for performance. | Remove from DOM or use hidden attribute |
| Opening | Backdrop fades in (opacity 0→1). Panel scales up or slides in. | CSS transition or animation. Use Transition Generator for values. |
| Open | Backdrop visible. Panel centered (or positioned). Focus trapped inside. Body scroll locked. | aria-modal="true", inert on background content |
| Closing | Reverse of opening animation. Focus returns to trigger. | Delay unmounting until animation completes |
| Nested | Second backdrop layers on top. Each dialog manages its own focus trap. | Maintain a dialog stack — close inner before outer |
Backdrop States
- Default: Semi-transparent black (
rgba(0,0,0,0.5)) - Blur: Frosted-glass effect (
backdrop-filter: blur(8px)). Creates depth but impacts performance on low-end devices. - Interactive: Clicking the backdrop closes the dialog. For alert dialogs, disable this — force users to make a choice.
Accessibility
WCAG Requirements
| Criterion | Level | Requirement |
|---|---|---|
| SC 1.3.1 Info and Relationships | A | Dialog must be marked with role="dialog" or use the native <dialog> element |
| SC 2.1.2 No Keyboard Trap | A | Users must be able to close the dialog via keyboard (Escape key) |
| SC 2.4.3 Focus Order | A | Focus must move into the dialog when it opens and return to the trigger when it closes |
| SC 4.1.2 Name, Role, Value | A | Dialog must have an accessible name via aria-labelledby or aria-label |
ARIA Attributes
role="dialog"— Standard dialog. Use the native<dialog>element when possible (it gives you a lot for free).role="alertdialog"— For dialogs that require user acknowledgment (confirmations, warnings). Screen readers announce these more urgently.aria-modal="true"— Tells assistive tech that content behind the dialog is inert. Essential.aria-labelledby— Point to the dialog's title heading.aria-describedby— Point to the dialog's description text (optional but recommended).
Focus Management
- On open: Move focus to the first focusable element inside the dialog, or the close button, or the dialog itself (with
tabindex="-1"). - While open: Trap focus within the dialog. Tab from the last focusable element should cycle back to the first.
- On close: Return focus to the element that triggered the dialog.
Keyboard Interaction
| Key | Action |
|---|---|
| Escape | Closes the dialog (unless role="alertdialog" requires explicit choice) |
| Tab | Cycles through focusable elements within the dialog |
| Shift + Tab | Cycles backwards through focusable elements |
The inert Attribute
Apply inert to all page content behind the dialog. This is superior to manual aria-hidden management because it also prevents mouse and keyboard interaction with background elements.
<main inert><!-- page content --></main>
<dialog open aria-labelledby="dialog-title" aria-modal="true">
<!-- dialog content -->
</dialog>
For more on accessible overlays, see our ARIA Attributes Guide and Keyboard Accessibility Guide.
Usage Guidelines
Do's
- ✅ Always provide a visible close mechanism — a close button, a cancel button, or both. Never trap users.
- ✅ Use descriptive titles. "Delete project?" is better than "Are you sure?" — the title should make the dialog's purpose clear without reading the body.
- ✅ Keep dialogs focused. One task, one dialog. If your dialog has tabs or complex navigation, it should probably be a page.
- ✅ Match the destructive action to a destructive button variant. Red "Delete" button, not a cheerful blue one.
- ✅ Animate the entrance (fade + slight scale) to orient users. A 200ms transition is enough — test values with our Transition Generator.
Don'ts
- ❌ Don't open a dialog on page load. Nothing says "we don't respect your time" like an immediate popup. Cookie banners are the one painful exception.
- ❌ Don't nest dialogs. If you need a confirmation inside a dialog, reconsider your flow. At most, use an inline confirmation within the existing dialog.
- ❌ Don't put critical information only in a dialog. Users dismiss them reflexively. Important info should live on the page itself.
- ❌ Don't use a dialog for success messages. Use a Toast instead.
- ❌ Don't disable the Escape key unless you have a very good reason (e.g., an unsaved-changes warning).
Content Guidelines
- Title: 3–8 words, action-oriented ("Confirm deletion", "Add team member")
- Body: Keep it under 3 sentences. If you need more, the content doesn't belong in a dialog.
- Actions: Place the primary action on the right. Use specific labels ("Delete project" not "OK").
- Destructive dialogs: Repeat the item name in the body text. "This will permanently delete My Project."
Code Snippets
html
<!-- Dialog using native <dialog> element -->
<button type="button" id="open-dialog" aria-haspopup="dialog">
Delete project
</button>
<dialog
id="confirm-dialog"
aria-labelledby="dialog-title"
aria-describedby="dialog-desc"
>
<header>
<h2 id="dialog-title">Delete project?</h2>
<button type="button" aria-label="Close" onclick="this.closest('dialog').close()">
<svg aria-hidden="true" width="20" height="20" viewBox="0 0 20 20" fill="currentColor">
<path d="M6.28 5.22a.75.75 0 0 0-1.06 1.06L8.94 10l-3.72 3.72a.75.75 0 1 0 1.06 1.06L10 11.06l3.72 3.72a.75.75 0 1 0 1.06-1.06L11.06 10l3.72-3.72a.75.75 0 0 0-1.06-1.06L10 8.94 6.28 5.22Z"/>
</svg>
</button>
</header>
<p id="dialog-desc">
This will permanently delete <strong>My Project</strong> and all its data.
This action cannot be undone.
</p>
<footer>
<button type="button" class="btn btn-secondary" onclick="this.closest('dialog').close()">
Cancel
</button>
<button type="button" class="btn btn-destructive">
Delete project
</button>
</footer>
</dialog>
<script>
const btn = document.getElementById("open-dialog");
const dialog = document.getElementById("confirm-dialog");
btn.addEventListener("click", () => dialog.showModal());
</script>tsx
import { useRef, useEffect, type ReactNode } from "react";
import { createPortal } from "react-dom";
interface DialogProps {
open: boolean;
onClose: () => void;
title: string;
description?: string;
children: ReactNode;
size?: "sm" | "md" | "lg";
}
export default function Dialog({
open,
onClose,
title,
description,
children,
size = "md",
}: DialogProps) {
const dialogRef = useRef<HTMLDialogElement>(null);
useEffect(() => {
const dialog = dialogRef.current;
if (!dialog) return;
if (open && !dialog.open) {
dialog.showModal();
} else if (!open && dialog.open) {
dialog.close();
}
}, [open]);
useEffect(() => {
const dialog = dialogRef.current;
if (!dialog) return;
const handleClose = () => onClose();
dialog.addEventListener("close", handleClose);
return () => dialog.removeEventListener("close", handleClose);
}, [onClose]);
const sizeClass = {
sm: "max-w-[400px]",
md: "max-w-[560px]",
lg: "max-w-[720px]",
}[size];
return createPortal(
<dialog
ref={dialogRef}
className={`dialog ${sizeClass}`}
aria-labelledby="dialog-title"
aria-describedby={description ? "dialog-desc" : undefined}
onClick={(e) => {
if (e.target === dialogRef.current) onClose();
}}
>
<div className="dialog-panel">
<header className="dialog-header">
<h2 id="dialog-title">{title}</h2>
<button type="button" aria-label="Close" onClick={onClose}>✕</button>
</header>
{description && <p id="dialog-desc">{description}</p>}
<div className="dialog-body">{children}</div>
</div>
</dialog>,
document.body,
);
}
// Usage
function App() {
const [open, setOpen] = useState(false);
return (
<>
<button onClick={() => setOpen(true)}>Delete project</button>
<Dialog
open={open}
onClose={() => setOpen(false)}
title="Delete project?"
description="This action cannot be undone."
size="sm"
>
<footer>
<button onClick={() => setOpen(false)}>Cancel</button>
<button className="btn-destructive" onClick={handleDelete}>
Delete project
</button>
</footer>
</Dialog>
</>
);
}Design Systems
Cross-System Comparison
| Feature | Material 3 | Shadcn/ui | Radix | Ant Design |
|---|---|---|---|---|
| Element | Custom <div> with portal | <dialog> via Radix | <div> with portal + focus trap | Custom <div> with portal |
| Focus trap | Built-in | Via Radix primitives | Excellent — FocusTrap + FocusScope | Built-in |
| Animation | Material motion system | CSS transitions (Tailwind) | BYO animation | CSS transitions (Ant Motion) |
| Nested dialogs | Supported | Supported via Radix | Full stack management | Supported but discouraged |
| Alert variant | Separate AlertDialog | AlertDialog (separate component) | AlertDialog primitive | Modal.confirm() static method |
| Close on backdrop | Configurable | Default true | Configurable | maskClosable prop |
| Scroll lock | document.body overflow hidden | RemoveScroll from Radix | RemoveScroll component | Body overflow hidden |
Notable Approaches
Radix sets the standard for dialog accessibility. Its Dialog primitive handles focus trapping, scroll locking, and portal rendering with the inert attribute on background content. If you're building a dialog from scratch, study Radix's implementation first.
Material 3 separates "Basic Dialog" (informational) from "Full-screen Dialog" (complex tasks). The full-screen variant replaces the entire view on mobile — essentially a temporary page — which solves the "dialog inside dialog" problem elegantly.
Shadcn/ui wraps Radix primitives with Tailwind styling. The AlertDialog is a separate component from Dialog, which enforces the correct role="alertdialog" and prevents developers from accidentally using the wrong pattern for confirmations.
Ant Design offers Modal.confirm(), Modal.info(), and similar static methods that let you open a dialog imperatively (without JSX). This is convenient for one-off confirmations but makes testing harder.
The native HTML <dialog> element has reached excellent browser support (97%+ globally as of 2026). It provides showModal() for modal behavior and show() for non-modal — consider using it as your base rather than a <div> portal approach.
OverlayModalPopupLightbox