Purpose and content model
Dialog represents a dialog box or similar interactive subwindow. Calling showModal() opens it modally in the top layer and makes the rest of the document inert. Calling show() opens a nonmodal dialog. Merely adding open displays a dialog without reproducing the complete modal-opening behavior.
A dialog contains flow content and should have an accessible name, usually derived from a visible heading. Keep its purpose narrow and provide a clear way to finish or cancel. Native dialog supplies important behavior, but the author still chooses appropriate initial focus, labels, error handling, and focus restoration.
Syntax and working example
<button type="button" id="open-help">Open help</button>
<dialog id="help-dialog" aria-labelledby="help-title">
<h2 id="help-title">Keyboard help</h2><p>Use Tab to move between controls.</p>
<form method="dialog"><button value="close">Close help</button></form>
</dialog>
<script>document.querySelector("#open-help").addEventListener("click", () => document.querySelector("#help-dialog").showModal());</script>Supported attributes and behavior
Open reflects its displayed state. Newer closedby behavior distinguishes dismissal modes such as any, closerequest, and none; check its support separately. A form with method=dialog closes the dialog rather than making a network request, and its submitter can supply a return value. Use showModal(), show(), close(), and relevant events deliberately. Do not add tabindex to the dialog element itself; put focus on an appropriate descendant.
Another practical pattern
<dialog open aria-labelledby="notice-title">
<h2 id="notice-title">Draft saved</h2>
<p>This nonmodal notice does not block the rest of the page.</p>
<form method="dialog"><button>Dismiss</button></form>
</dialog>Accessibility and browser notes
Choose initial focus based on the task, not simply the first destructive button. Let users cancel when the workflow permits it and return focus to a sensible place after closing. Avoid nesting unnecessary dialogs. A modal with a long body needs usable scrolling and should not obscure the focused control behind fixed actions.
Common mistakes
Do not simulate modality with open=true plus a dark overlay and assume focus is contained. Avoid calling showModal on an already open nonmodal dialog without managing its state. Native support for dialog does not imply support for every new dismissal attribute or declarative command.
Verify your implementation
Test keyboard entry, Tab order, Escape, cancellation, submission, and return focus. Repeat on a small viewport and at large text zoom. Inspect the dialog's accessible name and confirm background controls are unavailable only while the modal is open.
Standard status and sources
Standard; browser availability must be checked independently of specification status.