Learning objectives
Choose a disclosure, popover, or dialog by task; open a native modal dialog; test dismissal and focus restoration.
Prerequisites
Read accessible names and keyboard focus. Know basic JavaScript event handlers and native buttons.
Decide whether the rest of the page must be blocked
A disclosure reveals supporting content within the document flow. A popover presents content in the top layer without automatically making the rest of the page inert. A modal dialog interrupts the current task and limits interaction to the dialog until it closes. These are different experiences, even if all three look like a floating card in a design file.
Use a modal only when the task actually requires a focused decision or short interaction. A simple definition or navigation menu often does not justify blocking the page. Essential information should not disappear behind a popup that people may never discover. Keep the label of the triggering control specific about what will open.
Use the dialog API correctly
The dialog element can be opened non-modally with show or modally with showModal. Adding the open attribute makes it visible but does not reproduce all modal behavior. ShowModal places the dialog in the top layer and makes the rest of the document inert while the modal is active.
Give the dialog an accessible name, commonly by referencing its visible heading with aria-labelledby. Choose an appropriate initial focus target. A confirmation may focus the least destructive action; a long informational dialog may need focus on a heading or introductory element that can be programmatically focused. The right choice depends on the content and task.
A form with method="dialog" can close the dialog without sending a network request. A normal button can call close. Test Escape dismissal and the return of focus to the initiating control. Do not add a second generic focus trap without understanding how it interacts with native behavior.
Treat popovers as a separate pattern
The popover attribute and a button’s popovertarget can provide declarative show/hide behavior. Auto popovers can support light dismissal and coordination with other popovers. They do not automatically become accessible menus or modal dialogs; the content still needs the right semantics and keyboard interactions for its purpose.
Browser support for newer related attributes evolves. Feature-detect where a fallback is needed, and keep the underlying information available if the enhancement is absent. A native feature can reduce code, but testing remains necessary for focus, nested interactions, scrolling, and mobile keyboards.
Working example
<button type="button" id="open-dialog">Read workshop details</button>
<dialog id="workshop-dialog" aria-labelledby="dialog-title">
<h2 id="dialog-title">Workshop details</h2>
<p>The session lasts two hours. Bring a notebook.</p>
<button type="button" id="close-dialog">Close details</button>
</dialog>Another example
<button type="button" popovertarget="term-help">What is semantic HTML?</button>
<div id="term-help" popover><p>Semantic HTML describes the purpose of content using meaningful elements.</p></div>Expected output
The live example opens a modal within the playground’s document and closes through its explicit button. The second example uses a non-modal popover in supporting browsers. Its purpose is a short explanation, not a menu or blocking confirmation.
Common mistakes
Do not use the open attribute as a substitute for showModal. Do not label every floating panel a dialog. Avoid placing the only close control outside the modal, and do not prevent Escape dismissal without a compelling task-specific reason.
Accessibility and browser notes
Verify focus on opening, Tab behavior, Escape, explicit close, and focus restoration. Dialog content needs normal headings, labels, and readable text. Native modal behavior does not excuse inaccessible controls inside it.
Practice
Create a dialog with an explicit Cancel button that closes without submitting to a server.
Review the solution and reasoning
<dialog id="confirm" aria-labelledby="confirm-title"><h2 id="confirm-title">Review your changes</h2><p>You can return to editing.</p><form method="dialog"><button value="cancel">Cancel</button></form></dialog>Method dialog closes the dialog and can set its return value from the submitter. It is separate from a real server mutation. A production delete or purchase action would require its own authorized processing and feedback.