Code example
Common baseline
Set 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.
Design system implementations
Additional checks
Set aria-labelledby and aria-describedby explicitly
Connect aria-labelledby to the DialogTitle id and aria-describedby to the DialogContent id on the Dialog component. MUI does not wire these automatically.
Do not use keepMounted
keepMounted={true} keeps a closed Dialog in the DOM. Screen readers may read hidden content, so avoid this prop.
Use autoFocus for initial focus control
Add the autoFocus prop to the element that should receive focus when the modal opens — typically the primary confirm button.
Code sample
Implementation notes
- –aria-labelledby and aria-describedby are not set automatically by MUI and must be added explicitly to the Dialog.
- –Add autoFocus to set the initial focus target when the modal opens. The default confirm button is recommended.
- –DialogContentText automatically applies correct color contrast and typography styling.