Modal Dialog
An overlay component that demands user attention and interrupts the current task
Related WCAG criteria — click to view details
Code example
Common baseline
Applies to all design systemsSet role="dialog"
Set role="dialog" and aria-modal="true" on the dialog element.
Connect title with aria-labelledby
Link the modal's title to the dialog via aria-labelledby.
Focus trap
Keyboard focus must be confined within the modal and must not escape to the background.
Move focus on open
When the modal opens, move focus to the first focusable element or the dialog title.
Close with Escape
Pressing Escape must close the modal.
Restore focus on close
When the modal closes, return focus to the element that triggered it.
Prevent background scroll
Prevent scrolling of the background content while the modal is open.
Apply inert to background
Apply the inert attribute to background content to block screen reader access.
Add description with aria-describedby
If the modal has body text, connect it via aria-describedby.
Do not allow a scrollable background
A scrollable background while the modal is open causes users to lose context.
Do not implement without a focus trap
Without a focus trap, screen reader users can navigate behind the modal and become disoriented.
Additional checks
Caution with keepMounted
When keepMounted is used, the hidden Dialog remains in the DOM and may be exposed to screen readers.
Do not use disablePortal
disablePortal interferes with the focus trap and inert handling.
Code sample
Implementation notes
- –MUI Dialog handles focus trapping automatically.
- –Use the autoFocus prop to control initial focus position.
- –Use TransitionProps.onExited to restore focus after the dialog closes.