The native HTML <dialog> element gives the web a built-in model for modal and non-modal dialogs, including focus handling, a top layer, and the ::backdrop pseudo-element. Yet one product decision has often required extra JavaScript: exactly how should a dialog be dismissed? The closedby attribute makes that behavior declarative by distinguishing a close button, a platform dismissal action such as Escape, and a light dismiss action such as clicking outside the dialog.
What the closedby attribute controls
A dialog can be dismissed in several ways. A developer-provided button may call close() or submit a form with method="dialog". The browser may process a close request, commonly triggered by the Escape key. A user may also expect a click or tap outside a lightweight dialog to close it. These interactions are not equally appropriate for every interface.
The WHATWG HTML specification defines three closedby states:
none: only developer-specified mechanisms close the dialog.closerequest: a close request, such as Escape where supported, may dismiss it.any: light dismiss, close requests, and developer controls may all close it.
<dialog id="quick-settings" closedby="any">
<h2>Quick settings</h2>
<p>Adjust your reading preferences.</p>
<form method="dialog">
<button value="done">Done</button>
</form>
</dialog>This small attribute documents an important interaction rule directly in the markup. It also lets the browser coordinate behavior with the dialog's native lifecycle instead of requiring a document-wide pointer listener.
Choosing the right dismissal policy
Use closedby="any" for lightweight, easily reversible surfaces where users expect to click away: a quick settings panel, a simple chooser, or contextual help. It creates behavior similar to light-dismiss interfaces built with the Popover API, while retaining dialog semantics.
Use closedby="closerequest" when Escape should work but an accidental outside click should not discard the interaction. This is a reasonable default for many modal forms. Use closedby="none" sparingly, such as a critical step that must end through an explicit decision. Even then, provide clear actions and avoid trapping people in a surface they cannot understand or leave.
Modal and non-modal defaults
The way a dialog is opened matters. showModal() places it in the top layer, creates a backdrop, and makes the rest of the document inert while the modal is active. show() opens a non-modal dialog that does not block the page. The default closedby behavior differs according to that opening mode, so setting the attribute explicitly is useful when the intended interaction should be obvious to future maintainers.
const dialog = document.querySelector('#account-dialog');
const openButton = document.querySelector('#open-account');
openButton.addEventListener('click', () => {
dialog.showModal();
});You still use the familiar dialog methods and events. showModal() opens a modal dialog, close() closes it with an optional return value, and the close event reports completion. The cancel event is relevant to platform close requests and can be prevented when validation or another rule truly requires it. MDN's dialog element reference provides a useful overview of these APIs and accessibility considerations.
Build an accessible dialog first
Dismissal behavior is only one piece of accessible modal design. Give the dialog a clear heading, keep the purpose concise, and ensure every necessary action is reachable by keyboard. When a modal opens, focus should move inside it; when it closes, focus should return to a logical place, usually the control that opened it. Native dialogs help with this behavior, but developers must still choose sensible initial focus and readable content.
Avoid removing the visible focus indicator. Do not rely on clicking the backdrop as the only way to close a dialog. A clearly labeled button remains essential, especially for touch, switch, voice, and keyboard users. If the rest of a custom interface must be made non-interactive, review our guide to the HTML inert attribute; native modal dialogs handle this relationship for you.
Progressive enhancement and fallback
Because newer attributes reach browsers at different times, test closedby in the browsers and embedded webviews your audience uses. The core dialog remains functional even when an unknown attribute is ignored, provided that it includes an explicit close control. This makes progressive enhancement straightforward: start with a valid dialog and working button, then use closedby to improve native dismissal behavior where supported.
If product requirements demand identical light-dismiss behavior in an older browser, add a narrowly scoped fallback after feature detection. Keep that fallback separate from the essential close button, and take care not to treat every pointer event outside the visible rectangle as dismissal. Nested overlays, drag interactions, and screen magnification can make simplistic global listeners unreliable.
Common implementation mistakes
- Opening every dialog as modal even when the surrounding page should remain usable.
- Using
closedby="none"without an obvious, keyboard-accessible exit. - Closing on outside pointer-down and accidentally swallowing a user's intended action.
- Replacing native focus behavior with a fragile custom focus trap.
- Animating the dialog without honoring
prefers-reduced-motion. - Forgetting to test the dialog after dynamic content or validation errors appear.
For components that include encapsulated markup, Declarative Shadow DOM can help deliver the initial structure, but labels, focus order, and close controls must remain understandable across the boundary.
Clear intent in one attribute
The best part of closedby is clarity. A reader can inspect the element and immediately understand whether outside clicks, Escape, or only explicit actions should dismiss it. That reduces custom event code and creates room for browsers to deliver consistent platform behavior. Keep an explicit close button, choose the least restrictive policy that fits the task, and test with keyboards, touch, zoom, and assistive technology. The result is a dialog that feels predictable because its dismissal rules match its purpose.
Browse with calm, clarity, and purpose
Download Noorani Browser for a focused browsing experience with thoughtful privacy tools and useful everyday features.