The <dialog> Element

Technical Summary

Definition / Categories

Item	Normative organization
Meaning	A temporary dialog box for a task or information-gathering interaction
Categories	Flow content, Interactive content, and Palpable content
Context	Where flow content is expected
Content model	Flow content
Content attributes	Global attributes, closedby, and open
DOM interface	HTMLDialogElement with open, returnValue, show(), showModal(), close(), and requestClose()

open state and showing methods

open is a boolean attribute indicating that the dialog is active and interactive. Its presence alone does not determine whether the dialog is modal.

Operation	Normative boundary
show()	Shows a non-modal dialog while the rest of the page remains interactive
showModal()	Places the dialog in the top layer and shows it as the top-most modal dialog
close(result)	Closes the dialog, stores the result as returnValue, and fires close
requestClose(result)	Requests closing through cancel; if it is not canceled, the dialog closes

const dialog = document.querySelector('#settings');

dialog.show();       // non-modal
dialog.close('done');

dialog.showModal();  // modal, top layer
dialog.requestClose('cancel');

Modality, the top layer, and inertness

A dialog shown by showModal() is added to the Document's open dialogs list and treated as modal. The Document is blocked by the dialog, and the outside focused area becomes inert. Because the dialog is in the top layer, its stacking behavior cannot be understood only through the ancestor's z-index.

The area behind the dialog can be styled through ::backdrop. A dark overlay alone does not implement modal semantics or keyboard behavior; the showing method, focus, and close conditions must be evaluated together.

<dialog id="confirm" aria-labelledby="confirm-title">
  <h2 id="confirm-title">Confirm deletion</h2>
  <p>This action cannot be undone.</p>
  <form method="dialog">
    <button type="submit" value="cancel" autofocus>Cancel</button>
    <button type="submit" value="delete">Delete</button>
  </form>
</dialog>

<style>
  #confirm::backdrop { background: rgb(0 0 0 / 0.45); }
</style>

Focus, close requests, and events

The dialog focusing steps look for an autofocus target, a focus delegate, and then the dialog itself. If a particular descendant is the correct first interaction, authors should mark that intent with autofocus. When a modal closes, the user agent attempts to restore focus to the previously focused element.

close() is a direct close operation. requestClose() first fires a cancel event; unless it is canceled with preventDefault(), the close algorithm proceeds. This boundary allows Escape and other user close requests to share one cancellation point.

dialog.addEventListener('cancel', (event) => {
  if (mustConfirm) event.preventDefault();
});

dialog.addEventListener('close', () => {
  console.log(dialog.returnValue);
});

closedby and light dismiss

closedby is an enumerated attribute that defines which user actions close a dialog.

Value	Close condition
any	Close requests and clicks outside the dialog close it
closerequest	Close requests close it, but outside clicks do not
none	No user action automatically closes it
Missing or invalid	Auto; the computed closed-by state depends on conditions such as how the dialog was shown

Support and outside-click behavior must be checked for the target browser set and date. The specified keyword and an observed close condition are not the same evidence.

Form method="dialog" and returnValue

When a form's method is in the Dialog state, form submission closes the dialog containing the form instead of making a network request. The submitter's value is used as the dialog's result.

<dialog id="ship">
  <form method="dialog">
    <button type="submit" value="board">Board the ship</button>
    <button type="submit" value="call">Call the captain</button>
  </form>
</dialog>

ship.addEventListener('close', () => {
  if (ship.returnValue === 'board') {
    // Continue according to the choice.
  }
});

DOM Interface

HTMLDialogElement.open reflects the open attribute as a boolean. returnValue exposes the latest close result. The meanings of showing and closing should not be reduced to adding and removing an attribute.

const dialog = document.querySelector('#settings');

dialog.open;
dialog.returnValue;
dialog.show;
dialog.showModal;
dialog.close;
dialog.requestClose;

Fact / Evidence

Normative claims about meaning, showing methods, modality, focus, close requests, and form boundaries are separated from browser rendering, focus, and accessibility-tree observations in the Implementation Evidence section below.

Evidence

1. HTML Standard: The dialog element — meaning, categories, content model, open, closedby, focus, show, showModal, close, requestClose, and the top layer
2. HTML Standard: Form control infrastructure — method="dialog", submitters, dialog closing, and result values
3. HTML Accessibility API Mappings — entry point for dialog roles, accessible names, states, and platform API mappings
4. Web Platform Tests: the-dialog-element — related tests for dialog, modal, focus, close, and toggle behavior

Implementation Evidence

Browser implementation, WPT, and accessibility-tree observations are recorded separately from normative claims. dialog-v1 has been run in Chrome 153, and partial IMPL and accessibility-tree observations are registered. Unverified items are not marked as reviewed.

Dedicated fixture: dialog-v1 is a registered fixture for non-modal and modal display, initial focus, focus restoration, close requests, method="dialog", closedby, and returnValue. The fixture is stored in the repository as docs/atlas/dialog-v1-fixture.html and dialog-v1-check.js, with the execution record in docs/atlas/dialog-v1-results-2026-09-19.md.

Dialog placement, backdrop, Escape, outside clicks, focus, and accessibility-tree exposure may depend on the user agent, OS, attribute values, and showing method. A single-environment observation will not be registered as universal browser behavior.

Coverage / Open Issues

• CoveredMeaning, categories, context, content model, content attributes, and DOM interface
• Coveredshow() / showModal(), modal blocking, top layer, focus, close requests, and method="dialog" as normative entry points
• Coveredclosedby values, computed closed-by state, and the normative boundary for light dismiss
• Partially covereddialog-v1 passed 9 checks in Chrome 153 on Windows NT 10.0; named modal/non-modal accessibility-tree states and initial focus were observed
• OpenCross-browser comparison of focus, Escape, backdrop, outside clicks, close events, and focus restoration
• Openclosedby, command / commandfor, nested dialogs, popover interaction, implementation timing, and compatibility
• OpenIndividual WPT results, complete HTML-AAM mappings, platform API observations, and assistive-technology differences

This is initial coverage. It records the normative processing model without claiming identical rendering, focus, close conditions, or accessibility API results across browsers, or completion of the entire dialog element review.

Related surface

For a beginner-friendly explanation of dialogs, modality, focus, and method="dialog", see the dialog element page in Yugien. For the opening control, see the button element; for the boundary with expandable information, see the details element; for shared form submission, see the form element.