Skip to main content
Version: 8.0.0


Here is the basic markup, which can be enhanced as desired. Pay extra attention to the comments after the next code snippet.

<!-- 1. The dialog container -->
<!-- 2. The dialog overlay -->
<div data-a11y-dialog-hide></div>
<!-- 3. The actual dialog -->
<div role="document">
<!-- 4. The close button -->
<button type="button" data-a11y-dialog-hide aria-label="Close dialog">
<!-- 5. The dialog title -->
<h1 id="your-dialog-title-id">Your dialog title</h1>
<!-- 6. Dialog content -->
  1. The dialog container.

    • It is not the actual dialog window, just the container with which the script interacts.
    • It must have a unique name as data-a11y-dialog for automatic instantion through HTML, or as id for JavaScript instantiation.
    • It might need a class for you to be able to style it.
    • It should have an initial aria-hidden="true" attribute to avoid a “flash of unhidden dialog” on page load.
    • It may have the alertdialog role to make it behave like an alert dialog.
    • It doesn’t have to have the aria-labelledby attribute however this is recommended. It should match the id of the dialog title (which can be still hidden if desired so).
  2. The dialog overlay.

    • It doesn’t have to have the data-a11y-dialog-hide attribute, however this is recommended. It hides the dialog when clicking outside of it.
    • It should not have the data-a11y-dialog-hide attribute if the dialog is an alert dialog.
  3. The actual dialog.

    • It should be styled as a dialog (fixed on top of the page).
    • It should have the role="document" attribute to improve support in NVDA.
    • The script does not interact with it whatsoever.
  4. The dialog close button.

    • It does have to have the type="button" attribute.
    • It does have to have the data-a11y-dialog-hide attribute.
    • It does have to have an aria-label attribute (or otherwise accessible name) if you use an icon as content.
  5. The dialog title.

    • It should have a different content than “Dialog Title”.
    • It can have a different id than your-dialog-title-id.
  6. The dialog content.

    • This is where your dialog content lives.