Dialog element

The native HTML <dialog> element has come a long way. While it used to be very inconsistent, not to mention somewhat unfinished, it is now in a pretty healthy place and can generally be used — provided one is aware of the remaining caveats.

info

For extensive information about the <dialog> element, do read Having an open dialog and more importantly Use the dialog element (reasonably), from Scott O’Hara.

Remaining caveats

Here are some of the remaining issues with the HTML <dialog> element:

• Clicking outside the dialog does not close the dialog in some browsers such as Chrome.
• The ::backdrop pseudo-element only shows when programatically opening the dialog, not when using the open attribute.
• Default styles are left to the browsers’ discretion and can be inconsistent.
• The alert dialog pattern (role="alertdialog") does not work with the <dialog> element.
• The events emitted by the <dialog> element are a little confusing (there is both cancel and close but no open) and not very reliable (only fired in certain situations).
• Using the <dialog> element still requires JavaScript (unlike <details> for instance).

note

If you are aware of a downside or pitfall of the <dialog> element that was not mentioned here, please kindly open an issue so we can keep this document relevant and informative.

Why a11y-dialog

This brings us to the reasons why one may stick to using a11y-dialog (or a similar library):

• Needing cross-browser consistency. Browsers may apply different styles to the <dialog> element, or may handle user interactions slightly differently.
• Needing to support browsers that do not support the <dialog> element. Google has created a polyfill for <dialog>), but it is larger than a11y-dialog, provides fewer features, and doesn’t cover all the accessibility expectations that a dialog should covers.
• Needing alertdialog support. There is no plan for the <dialog> element to support role="alertdialog" as of today, so if that’s a need, then a11y-dialog remains a good option.
• Building interactions that rely on events. The native <dialog> element supports cancel and close events, but their behaviors aren’t reliable. The <dialog> does not support an open event at all.
• Using a framework-specific wrapper around it, like React or Vue.js. It’s going to be easier to integrate with a11y-dialog than the native element.
• Relying on a11y-dialog in an existing project already and not wanting to migrate to the <dialog> element. a11y-dialog is about 1.4Kb when minified and gzipped, and even smaller when compressed with brotli. It won’t add significant bloat to your application.