Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / HTML

aria-modal — modal dialog semantics

The aria-modal attribute tells assistive technologies whether a displayed element is modal, meaning interaction is restricted to its contents. It does not block the background or manage focus by itself: the declaration must match the interface's actual behavior.

Version: WHATWG HTML Living Standard; index snapshot date recorded separately

Syntax

aria-modal="true" | aria-modal="false"

aria-modal is a WAI-ARIA property used in HTML to indicate whether a displayed element is modal. The value true indicates modality; false is the default. This property takes the text values true and false, rather than following HTML boolean-attribute syntax: do not write the attribute name without a value. It is supported on the dialog and alertdialog roles, not globally on arbitrary elements.

aria-modal="true" communicates semantics to assistive technologies, which may restrict navigation to the dialog's contents. It does not open a dialog, block background clicks, or move or contain focus. Set it only when the interface actually prevents all users from interacting with content outside the dialog and visually dims or obscures the background.

On opening, move focus inside the dialog and keep the Tab and Shift+Tab sequence within it. Provide an internal close button and support Escape; on closing, usually restore focus to the invoking element. Give the dialog an accessible name, for example through aria-labelledby referencing its visible heading. All controls needed to operate the dialog must be its descendants.

The example uses a native dialog opened with showModal() rather than recreating modal behavior manually. Explicit aria-modal="true" is redundant in this case because native modality is already exposed to assistive technologies; it remains to demonstrate the syntax. Adding the attribute to an ordinary container alone does not provide this behavior. Check keyboard operation and accessibility-tree semantics separately.

Examples

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>aria-modal example</title>
<style>
  dialog::backdrop { background: rgb(0 0 0 / 50%); }
</style>
<button id="open" type="button">Open dialog</button>
<dialog id="notice" aria-modal="true" aria-labelledby="heading">
  <h2 id="heading">Notice</h2>
  <p>This dialog blocks interaction with the page.</p>
  <button id="close" type="button" autofocus>Close</button>
</dialog>
<script>
  const opener = document.getElementById('open');
  const notice = document.getElementById('notice');
  const closer = document.getElementById('close');
  opener.addEventListener('click', () => notice.showModal());
  closer.addEventListener('click', () => notice.close());
  notice.addEventListener('close', () => opener.focus());
</script>
</html>

Result

Initially, only Open dialog is visible. Activating it opens Notice, dims the background, and focuses Close. Background controls cannot be activated while the dialog is open. Close or Escape dismisses the dialog and returns focus to Open dialog.

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources