Modal dialog

Component preview

A focused surface for a contained task that makes the rest of the page temporarily inactive.

Build pack

Turn this concept into a useful prompt

Choose the task and destination. Technical names stay in English.

What do you want to do?

CreateModifyRepair

Where will you use the prompt?Prompt languageLanguage of the interface to build

Your objective

In your own words

What people describe

Documented aliases: modal, dialog, modal window

a window over the page for editing details
open a form and block the background
a centered box I must finish or close
show settings without leaving this page
a popup that traps focus until closed
an overlay for a short contained task

Try it

Modal surfaces

Compare all three behaviors

Shared comparison scenario: A project item opens a focused overlay while the underlying workspace remains unavailable until the user finishes or closes it.

This context stays fixed. Switch concepts to observe the mission, edge case, and specimen specific to each behavior.

Your task

Open the dialog, tab through every control, cancel with Escape, and verify focus returns to Edit member.

Edge case to verify

A validation error keeps the dialog open, links the message to the invalid field, and moves focus only when submission fails.

Parts of the specimen

Use it when

Editing a compact record without losing page context
Completing a short focused form

Avoid it when

The workflow is long enough to deserve its own page
The information can remain nonmodal and contextual

Compare similar concepts

An Alert dialog is for a short consequential decision, not a general form and not a media viewer.

Alert dialog

Lightbox is a media-specific modal composition; a general Modal dialog handles tasks and an Alert dialog handles a consequential decision.

Lightbox

Technical details

Behaviors

Contain focus
While modal, keyboard focus stays inside the surface until it closes.
Dismiss with Escape
Escape closes the temporary surface and returns focus to a sensible control.

States

Dialog closed
Dialog closed
Dialog open
Dialog open

State transitions

Dialog closed → Dialog open
The edit trigger is activated and focus enters the bounded task.
Dialog open → Dialog closed
The task is saved or cancelled, or Escape safely closes it, then focus returns to the trigger.

Test scenarios

Context: A team member card opens a short form to edit role and display name.
Mission: Open the dialog, tab through every control, cancel with Escape, and verify focus returns to Edit member.
Primary state: The edit form opens with its title announced and focus on the first useful field.
Edge case: A validation error keeps the dialog open, links the message to the invalid field, and moves focus only when submission fails.

Accessibility

Role: dialog with aria-modal=true
Accessible name: The primary control or named region has a stable accessible name from visible text or an explicit programmatic label; placeholder text and tooltips are not names.
Focus: Opening moves focus inside, Tab cannot reach the inert page, and closing restores focus to the logical opener.
Dismissal: Cancel, the named close control, and Escape close without saving; outside press is enabled only when accidental loss is harmless.
Scroll: Background scrolling is locked while the modal is open. Overflow scrolls inside the surface and the focused control remains visible.
Announcement: Assistive technology receives the dialog role, accessible title, description, and validation updates.
Keyboard: Tab and Shift+Tab cycle inside the dialog
Escape closes when cancellation is safe
Enter submits only from the intended control

Bindings

Dialog.Root
implementationKind
radix
nativeElement
Not applicable
ariaPattern
dialog
radixPrimitive
Dialog
shadcnRecipe
Dialog
runtimeDependency
@radix-ui/react-dialog@1.1.19
packageName
@radix-ui/react-dialog
exportName
Dialog.Root
exactVersion
1.1.19
status
verified
verifiedAt
2026-07-16
deprecationStatus
active
replacement
Not applicable
validFrom
Not applicable
validUntil
Not applicable
Equivalence caveat: Radix Dialog supplies modal focus mechanics, while labeling, destructive-action wording, layout, and testing remain application work.
Verify binding source

Sources

WAI-ARIA APG: Dialog Modal Pattern
W3C WAI · standard · 2026-07-16
Claim covered: Modal dialog: modal dialog labeling, initial focus, focus containment, Escape dismissal, and focus return guidance.
Radix Primitives: Dialog
Radix Primitives · documentation · 2026-07-16
Claim covered: Modal dialog: documented Radix Dialog parts, modal focus management, portals, overlay, and dismissal hooks.

Verified on 2026-07-16 · rev. 1

Owner: SkillCodex Editorial
Status: review
Review: Independent editorial review pending
Next review: 2026-10-16
Publication: Not published
Change history: Initial sourced MVP draft; independent language review pending.