Search
Enter at least two characters without personal information.

    LibraryArticles & FAQ Your projectRequest a quote
    LanguageEN
    Practical guides

    Design and test a modal dialog

    A modal dialog suspends interaction with the rest of the page. It suits a short decision that requires an answer before continuing. Long reading, a service description or a complex form may work better on a dedicated page.

    Go to the method

    Tablet displaying a window above a page
    AI-generated illustration

    Justify the interruption

    Define what the person must decide and why they cannot continue without it. Reserve confirmation for consequences that deserve a real check. Repeated dialogs for easily reversible actions slow work and may make important confirmations less noticeable.

    Use a title that identifies the object and explicit actions. For an attachment, “Remove document” is clearer than “OK”. Explain whether removal deletes the file permanently or only removes it from the displayed folder. Preserve previous input when the person cancels.

    Plan focus and a way out

    The W3C dialog pattern describes moving focus inside on opening, keeping Tab navigation within the dialog and returning focus logically afterwards. A visible close control and Escape provide a way out. Do not mark a window modal while its background remains interactive.

    The HTML dialog element opened with showModal() makes the rest of the document inert. It does not choose the wording, initial focus or saving rules. Test the integrated dialog, including a case where deletion removes its original trigger.

    Check the accessible name, declared modality and actual behaviour separately. A title referenced by aria-labelledby names the window; aria-modal="true" exposes modality to assistive technology but does not itself block background clicks or focus. Test both interactions. An ancestor hidden with aria-hidden must not also contain the active dialog.

    For a confirmation containing several paragraphs or a table, initially focusing its heading with tabindex="-1" can keep the start available for reading without scrolling it out of view. The heading does not become an extra Tab stop. For a decision that is hard to reverse, consider the least destructive action instead. Record the initial and return targets: they depend on the content and workflow, rather than simply the first available button.

    Scroll the table horizontally to read every column. With a keyboard, focus the table area and use the arrow keys.

    Modal dialog: four focus transitions to check
    SituationExpected behaviourFailure to look for
    Opening long contentThe beginning stays visible; an internal target supports reading from the start.Focus jumps to an action after essential information.
    Tab from the last controlFocus reaches the first control within the dialog.Focus reaches a page link behind the window.
    Escape during confirmationThe window closes without executing the unchosen action.Dismissal triggers deletion or implicit confirmation.
    Closing after the trigger disappearsFocus reaches a target that makes sense for the next task step.Focus is lost or returns to a removed element.
    • W3C APG : Modal dialog

      Guidance consulted on 22 October 2026; this is a test checklist, not an audit result for the installed component.

    Handle long content and delayed operations

    On small screens, the title and close control must remain reachable. Check scrolling and whether a phone keyboard obscures the active field. If substantial reading is necessary, compare a dedicated page rather than layering several dialogs.

    Separate waiting from success when an operation reaches a remote service. Failure should preserve enough context for recovery. Closing the interface does not prove a server operation was cancelled. Define the actual behaviour and avoid promising cancellation the service cannot perform.

    Example: remove a document from a folder

    Educational example: “Remove quote.pdf from this folder?” identifies the document and says the original file is retained. Cancellation changes nothing. After removal, confirmation describes the result and focus reaches a nearby list control. The test covers failure and a missing original trigger using test documents.

    Check opening, closing and focus in a confirmation dialog.

    Synthetic case: a confirmation opens from a button deleting a fictitious draft. Test keyboard focus entry, intended closing methods and return to the trigger. Distinguish showModal() from merely showing a box: modality also affects interaction with the background. Moving focus must not itself confirm an action.

    • The dialog has a clear name, focus remains coherent and closing performs no unchosen action.
    • MDN HTML Dialog

      HTML element for modal or non-modal dialogs with native behaviour to verify within the user journey.

    Reference documents

    Content updated on

    Acceptance matrix to adapt to your project

    These proposed checks use synthetic cases. Decide the required behaviour with the team, record the result and assign unresolved gaps before release.

    Scroll the table horizontally to read every column. With a keyboard, focus the table area and use the arrow keys.

    Test cases, expected outcomes and useful evidence
    CaseExpected outcomeEvidence to retain
    Keyboard openingThe title and actions are reachable insideTrigger element, announced title, initial focus and tab order inside the dialog.
    CancellationPrevious information is preservedValues before and after closing
    Long mobile contentClosing and inputs remain usableViewport and screenshot
    Remote failureSuccess and failure are distinguishedMessage and recovery option

    Frequently asked questions

    Should confirmation receive initial focus?

    Choose by task and consequence. Starting at the content or the least destructive action can be preferable when reading is necessary or reversal is difficult.

    Is clicking the backdrop enough?

    Provide a visible control for people unable to use that gesture. Test Escape and focus return too.

    Can one dialog open another?

    That adds states and focus paths. Prefer a simpler journey where possible; if nesting is necessary, check each level of closure.