Tab moves behind the modal
← Back to incidents
React incident
Modal opens visually but fails screen-reader users
The modal looks fine on screen, but keyboard focus escapes behind it and screen readers do not announce it properly.
Intermediate15 min
Failure signals
The clues you start with
Screen reader does not announce the modal title
Focus does not return to the button that opened it
Overview
What failed in production?
Start by making the bug legible: what the user saw, why it mattered, and what the product was doing underneath.
Symptom
A billing confirmation modal opens, but keyboard users can tab into the page behind it and the screen reader says only 'group' instead of the dialog title.
User impact
Screen-reader and keyboard users lose track of where they are and may hesitate to confirm a destructive action.
Environment
Custom React portal modal built from divs and an overlay, not from a real dialog component.
Evidence pack
What you can inspect before answering
Note
Keyboard walkthrough
Tab leaves the visible modal and lands on navigation links behind the overlay.
Log
Screen reader check
The modal root has no dialog role and no accessible name.
Snippet
Current markup
<div className="overlay">
<div className="modal">
<h2>Delete card?</h2>
<button>Confirm</button>
</div>
</div>Stage 1: likely root cause
What is actually broken here?
Look for the missing dialog behavior, not just the visuals.
The only issue is that the confirm button text is too short.
Clearer button text helps, but it does not explain why the modal has no name or why focus escapes behind it.
The modal needs a higher z-index so screen readers can detect it.
Z-index changes what people see, not what a screen reader understands.
This is mostly a VoiceOver bug, so the app should not change much.
The current markup and focus behavior are objectively incomplete; blaming the tool misses the app defect.
The custom modal is missing the basics of a real dialog: a name, correct focus handling, and blocking the background.
Correct. This modal is missing the basic behavior of a real dialog.
Stage 2: debug priority order
What would you check first? Put the best three at the top.
Check keyboard and screen-reader behavior before debating implementation details.
- #1Run a keyboard-only open, tab, shift-tab, and escape walkthrough.
- #2Check whether the modal has dialog semantics, a clear name, and the right aria-modal value.
- #3Check that focus moves into the modal on open and returns to the trigger on close.
- #4Tune overlay animation timing to make the modal feel clearer.
- #5Adjust background colors first to improve clarity.
Only the top 3 positions are scored.
Expected: Run a keyboard-only open, tab, shift-tab, and escape walkthrough.
Expected: Check whether the modal has dialog semantics, a clear name, and the right aria-modal value.
Expected: Check that focus moves into the modal on open and returns to the trigger on close.
Stage 3: best fix set
Which changes should be in the real fix?
Pick the updates that make this behave like a real dialog for keyboard and screen-reader users.
Use a real dialog primitive, or add proper dialog semantics and a clear accessible name.
Correct. The modal needs a real dialog role and a name the screen reader can announce.
Rewrite placeholders and rely on that as the accessibility improvement.
Helpful copy is not a substitute for dialog semantics and focus management.
Remove the close button so there are fewer focusable elements to manage.
That makes the modal harder to use and avoids the real accessibility work.
Move focus into the modal on open, trap it while open, and restore it to the trigger on close.
Correct. Focus lifecycle is central to usable modal behavior.
Prevent background interaction and tabbing while the modal is open.
Correct. Background content should not compete with the active dialog.
Stage 4: regression guard
What is the best way to make sure this does not break again?
Pick the safeguard that checks real behavior, not just markup.
Add an aria linter rule and assume the interaction will stay correct.
Linting helps, but it cannot prove focus movement and background isolation.
Add an automated test for keyboard flow, focus return, and accessibility assertions.
Correct. This protects the actual behavior users depend on.
Replace the design with blocking browser alerts everywhere.
That discards the product UX instead of maintaining an accessible modal implementation.
Add a screenshot regression because the modal looked right visually.
Visual regression is insufficient for keyboard and screen-reader behavior.
You saw the overlay, but not the real dialog behavior
The modal still needs the basic accessibility behavior that makes it act like a dialog.
Good direction, but one key behavior is still missing
You found most of the fix, but the debug order or guardrail still missed an essential modal behavior.
You treated the modal like a real dialog
You covered semantics, focus behavior, and keeping the background inactive while the modal is open.
Ideal runbook
How a strong answer should flow
- 1Walk the flow with keyboard first.
- 2Check dialog semantics and naming next.
- 3Verify focus entry and return behavior.
- 4Lock the behavior with an automated accessibility regression.
Reflection
Reflection note
If you could do only one manual check here, which tool would give you confidence fastest?
0/240
Modal interview shortcut
A modal is not just a box on the screen. It needs the right semantics and focus behavior.
Strong answer checklist
- Named dialog
- Focus enters on open
- Focus stays inside
- Focus returns on close
- Background is not interactable