Skip to main content
Accessibility Field Guide

Modals and Dialogs

A practical Field Guide page about making modals and dialogs understandable, keyboard-accessible, and easy to escape.

A bright apartment hallway with several open doors.
Photo: Apartment Hallway with open Doors via Pexels — https://www.pexels.com/photo/apartment-hallway-with-open-doors-19878508/
View full screen Download image

A modal is not just a box that appears on top of the page.

It is a temporary place where the user's attention, keyboard focus, and next decision are supposed to move.

That makes modals easy to get wrong.

A dialog can look polished and still be hard to use if focus stays behind it, if the title is not exposed, if the keyboard gets trapped in the wrong place, or if the user cannot easily close it.

The goal is not to ban every modal.

The goal is to use them only when they help the task, and to make sure they behave like a real, understandable part of the interface when they appear.

The common project moment

A team needs a small interruption in the workflow.

Maybe the user needs to confirm a destructive action. Maybe they need to choose from a short list. Maybe they need to read important instructions before continuing. Maybe a form opens in a panel over the current page because it feels lighter than building a new route.

In the design file, the modal looks clear:

  • a dark overlay
  • a centered box
  • a title
  • a close icon
  • a primary action
  • a secondary action
  • maybe a small form or warning message

Visually, the screen says, "deal with this first."

But the code may tell a different story:

  • keyboard focus remains on the page behind the modal
  • a screen reader user is not told that a dialog opened
  • the dialog has no accessible name
  • the close button is named only X
  • tabbing moves into the page behind the modal
  • the Escape key does nothing
  • focus disappears after the modal closes
  • the modal contains too much content for a small overlay
  • the user is blocked by a modal that was not necessary in the first place

That gap is where many modal accessibility problems live.

The visual layer says the user is inside a temporary task.

The keyboard and assistive-technology layer may still think the user is somewhere else.

Start by asking whether it needs to be a modal

Before fixing modal behavior, ask whether the modal is the right pattern.

A modal interrupts the current page. It narrows the user's choices. It usually prevents interaction with the rest of the page until the user responds.

That can be appropriate when the user truly needs to make a focused decision before continuing:

  • confirming a destructive or irreversible action
  • completing a short required step
  • choosing between a small number of immediate options
  • reviewing a short warning that directly affects the next action

It may be the wrong pattern when the content is long, complex, optional, or better handled as part of the page:

  • a full multi-section form
  • long instructions
  • dense help content
  • a complicated comparison table
  • anything users may need to reference while working elsewhere on the page

If the user needs to read, compare, copy, navigate, or complete a longer task, a normal page, inline section, details disclosure, or dedicated workflow step may be easier to use.

A modal should earn the interruption.

Give the dialog a clear title

A dialog needs a name.

The visible title is usually the best source for that name.

For example:

<div role="dialog" aria-modal="true" aria-labelledby="delete-title">
  <h2 id="delete-title">Delete uploaded document?</h2>
  <p>This removes the document from your application.</p>
  <button>Cancel</button>
  <button>Delete document</button>
</div>

The title tells the user what opened and what decision they are being asked to make.

Vague titles make the interaction harder:

  • Confirm
  • Notice
  • Warning
  • Information
  • Dialog

Better titles name the task or decision:

  • Delete uploaded document?
  • Choose a mailing address
  • Add household member
  • Session ending soon
  • Review submission warning

A clear dialog title also helps reviewers.

If the title is specific, it is easier to check whether focus moved to the right place, whether the accessible name matches the visible title, and whether the user understands why the dialog appeared.

Move focus into the dialog when it opens

When a modal opens, keyboard focus should move into the modal.

Do not leave focus on the button, link, table row, or page element behind the overlay.

A user who opens a dialog with the keyboard should be able to keep using the keyboard without guessing where they are.

The right initial focus depends on the dialog:

  • For a simple confirmation, focus may move to the safest useful action, such as Cancel, or to the dialog title if the message needs to be read first.
  • For a short form, focus may move to the first field if the user clearly opened the dialog to complete that form.
  • For a warning with important text, focus may move to the title or a focusable container so the user hears the context before reaching the actions.

The important point is that focus should not stay behind the dialog.

If focus stays behind the dialog, the user may tab through a page they can no longer see or operate. That is confusing, and it can make the modal feel broken even when it looks fine visually.

Keep keyboard focus inside the modal while it is open

A modal should keep keyboard focus inside itself until it closes.

When the user presses Tab, focus should move through the controls in the dialog. When they reach the last control and press Tab again, focus should wrap back to the first control. Shift + Tab should move backward the same way.

Focus should not move into the dimmed page behind the modal.

That background page is visually unavailable. It should not remain keyboard-available as if nothing changed.

This does not mean the user is trapped forever.

It means the user's available choices while the modal is open should match what the interface is showing:

  • complete the modal task
  • choose a secondary action
  • cancel or close the dialog when closing is allowed

If the dialog cannot be dismissed, be very careful. Non-dismissible modals can block people from recovering, reviewing information, or escaping an accidental path.

Make closing clear and reliable

Most dialogs need a clear way out.

That usually means more than a small X icon.

Useful close options include:

  • a visible Cancel or Close button
  • a close icon with an accessible name such as Close dialog
  • support for the Escape key when dismissing is safe
  • returning focus to the control that opened the dialog

The close control should be a real button, not a clickable div.

For example:

<button type="button" aria-label="Close dialog">
  <svg aria-hidden="true" focusable="false">...</svg>
</button>

If the visible control is only an icon, the accessible name needs to explain the action. X is not enough. Close dialog is clearer.

If closing would discard user-entered information, the dialog may need to warn the user or provide a clearer cancel path. But it should still be understandable and operable.

Return focus when the dialog closes

When the modal closes, focus should land somewhere sensible.

Most of the time, focus should return to the control that opened the modal.

For example:

  • The user activates Delete document in a document row.
  • A confirmation dialog opens.
  • The user chooses Cancel.
  • Focus returns to the Delete document button or another logical control in that same row.

That return path matters because the user needs to continue from where they were.

If focus jumps to the top of the page, disappears, or lands behind the scenes, the user has to rebuild their place in the workflow.

Sometimes the original opener no longer exists after the modal action.

If the user confirms deletion, focus may need to move to a nearby remaining item, a status message, or the next logical place in the task. The key is to make the landing intentional, not accidental.

Keep the background from competing with the dialog

A modal should make the background unavailable while it is open.

Visually, teams often add an overlay to show that the page behind the dialog is not the active area.

Programmatically, the same idea matters.

Users should not be able to tab into background links, buttons, form fields, or controls while the modal is open. Screen reader users should not have to wade through the entire background page before finding the dialog.

Modern implementations may use the native dialog element, aria-modal="true", inert, or framework-provided modal behavior. The exact implementation can vary.

The review question is simpler:

While the modal is open, can users stay oriented inside the modal without the background page interfering?

If the answer is no, the modal is probably not behaving like a modal yet.

Be careful with content length and scrolling

Modals get harder when they contain too much.

A short confirmation may work well in a dialog. A long form, dense policy explanation, or multi-step task can become frustrating.

Watch for these signs:

  • the modal scrolls inside the page, but the page behind it also scrolls
  • the title or actions disappear while the user scrolls the modal body
  • focus moves to controls the user cannot see
  • mobile users cannot reach the bottom actions easily
  • screen magnification makes the dialog feel like a tiny page inside a page

If the modal needs its own long layout, it may need to become a page.

A focused interruption should stay focused.

Do not depend on visual dimming alone

A dark overlay can help sighted users understand that the background is inactive.

It does not make the modal accessible by itself.

The dialog still needs:

  • a clear role or native dialog pattern
  • a useful accessible name
  • intentional initial focus
  • keyboard operation
  • a reliable close path
  • focus containment while open
  • focus restoration after close

Visual styling can support the pattern, but it cannot replace the behavior.

If the overlay is the only thing telling the user what happened, the modal is incomplete.

Questions teams can ask

During design and content

  • Does this interruption truly need to be a modal?
  • Is the dialog title specific enough to explain the task or decision?
  • Is the content short enough for a focused overlay?
  • Is there a visible and understandable way to cancel or close when closing is allowed?
  • Are destructive or final actions labeled with the object they affect?
  • What should happen if the user dismisses the dialog accidentally?

During development

  • Is the dialog using a native or well-tested modal pattern instead of a custom clickable box?
  • Does the dialog expose a clear accessible name, usually from its visible title?
  • Does focus move into the dialog when it opens?
  • Does focus stay inside the modal while it is open?
  • Does Escape close the dialog when dismissing is safe?
  • Are background controls unavailable while the modal is open?
  • Does focus return to a logical place when the dialog closes?

During QA

  • Can you open, use, and close the modal with only the keyboard?
  • Does tab order stay inside the modal until it closes?
  • Does the first focused item make sense for the dialog's purpose?
  • Is there a visible focus indicator throughout the dialog?
  • Does a screen reader announce the dialog title and useful context?
  • Can the user recover if they choose the wrong path?
  • Does the dialog still work at mobile sizes, high zoom, and with longer translated text?

Common trail hazards

  • A modal opens visually, but focus stays behind it.
  • Tabbing moves into the background page.
  • The dialog has no accessible name or uses a vague title such as Confirm.
  • The close icon is an unnamed button or a clickable div.
  • The Escape key does not work when users reasonably expect it to.
  • Focus disappears or jumps to the top of the page after close.
  • The modal contains a long task that should be a page.
  • Background content is visually dimmed but still available to keyboard or screen reader users.
  • The primary action is specific visually, but its accessible name is vague.
  • Mobile or high-zoom users cannot reach the dialog actions.

Small habit

Test the modal without touching the mouse.

Open it from the keyboard. Notice where focus lands. Press Tab through every control. Try Shift + Tab. Try Escape if closing should be allowed. Close or cancel the dialog and see where focus returns.

Then ask:

Did the keyboard path match the visual story?

If the modal looks like the active task, the keyboard should behave that way too.

That one habit catches a lot of problems before formal review.

Use these as trail markers, not as the whole conversation:

  • Status Messages and Alerts — for feedback that appears after a user submits, saves, deletes, or waits for something to finish.
  • Focus Visible and Focus Order — for deciding where focus should move when a dialog opens, closes, or blocks the page.
  • Keyboard-Only Navigation — for checking whether the dialog can be opened, used, and dismissed without a mouse.
  • Tabs — for dialogs that contain tabbed panels or settings sections.
  • Accessible Names — for labeling dialog titles, close buttons, and controls inside the modal.

What to do next