Security Fundamentals

Build Accessible Dialogs and Modal Interactions

Implement modal dialogs with predictable focus, keyboard controls, accessible names, and appropriate background behavior.

Build Accessible Dialogs and Modal Interactions

Overview

A dialog must communicate its purpose, manage focus, support dismissal, and avoid trapping users in an inaccessible state.

Prefer native dialog behavior where suitable

The HTML dialog element provides a platform primitive for modal and non-modal dialogs. Use showModal() for modal behavior and provide a clear accessible name through a heading referenced by aria-labelledby. Keep a visible close button and do not rely on clicking the backdrop as the only dismissal method.

Manage focus and keyboard input

When opened, focus should move to a sensible element inside the dialog. Tab and Shift+Tab should remain within a modal dialog while it is open. Escape should close it when dismissal is safe. When closed, return focus to the element that opened it. Ensure the page behind the modal is not operable while modal state is active.

<dialog aria-labelledby="confirm-title">
  <h2 id="confirm-title">Confirm changes</h2>
  <p>Your settings will be updated.</p>
  <button type="button">Cancel</button>
</dialog>

Avoid unnecessary modals

A modal interrupts the current task and should be reserved for decisions or focused workflows that need attention. Inline disclosure, a dedicated page, or a non-modal popover may be less disruptive. Do not use dialogs for routine success messages that can be announced inline.

Test the complete interaction

Test keyboard-only operation, screen-reader announcements, zoom, small screens, nested content, validation errors, and repeated open-close cycles. Verify that focus is restored even when the original trigger is removed or rerendered.

Implementation checklist

  • Define the expected behavior and supported environments.
  • Keep security, accessibility, and failure states in the design.
  • Measure the result with representative user journeys.
  • Document operational assumptions and review them after changes.
Share this page Help other developers discover this resource.