Accessible Dialog Box

HTML dialog boxes are created by displaying and styling page content as a dialog box (usually with lightbox effect) in the middle of the page.

Such dialog boxes are often not accessible - they might not capture the keyboard focus or it might not be clear to a screen reader user that a dialog box was opened or how to access it.

The code below is an example of an HTML dialog box with a good level of accessibility. Simply download the script and style sheet, add them to your page and specify the id of the trigger link (the link that opens the dialog box) and the id of the element that holds the content for the dialog box.

Try here:

Code example:

<script type="text/javascript" src=""></script> 
rel="stylesheet" href="vadialog.css">
type="text/javascript" src="vadialog.js"></script>
<script type="text/javascript"> visionaustralia.addDialog("linkOne", "dialogOne", fbefore, fclose);

id="linkOne">Test old viking saying</button>
<p>Lorem ipsum...</p>
<p>Lorem ipsum...</p>
id="dialogOne" style="display:none;">
<h1>Old Viking Saying</h1>
Did they really use to say "Holy goat, where's my boat"?</p>
type="button" value="Absolutely" onclick='visionaustralia.closeDialog("dialogOne");'/>
type="button" value="Not sure" onclick='visionaustralia.closeDialog("dialogOne");'/>


The "vadialog.css" and "vadialog.js" files can be obtained from our Downloads page.

When the page loads, the script adds:

  • An event listener to the trigger link - this will open the dialog when link is clicked

When the trigger link is clicked, the following happens:

  1. The content (wrapper element) is copied to memory and removed from the HTML
  2. All child elements of the <body> element are given the "aria-hidden" attribute
  3. A "Close dialog" button is added at the top of the content
  4. Hidden text "Dialog start" and "Dialog end" are inserted at the very start and end of the content
  5. A grey overlay is placed on the page
  6. Content is re-inserted in the source code at the bottom of the page
  7. Content is displayed in a dialog box in the middle of the page
  8. Keyboard focus is moved to "Dialog start" at the top of the dialog box. This informs screen reader users that a dialog was opened (because the text "Dialog start" is read) and places the reading point at the start of the dialog. Keyboard and screen reader users can now move down to read/interact with the dialog.

Steps 1 and 6 are only included to ensure this dialog works wherever the content is originally placed in the DOM. If you write your own code, the steps can be omitted if the content is already a child of the <body> element.

When the dialog box is closed:

  1. Child elements of the <body> element have aria-hidden values restored to previous values 
  2. Keyboard focus is moved back to the trigger link


The dialog is modal for mouse and keyboard users, as the grey overlay prevents interaction with other page content for mouse users and keyboard trapping anchors are used to keep keyboard focus inside the dialog box.
For screen reader users the modality is provided by applying the aria-hidden="true" attribute for all page content except the dialog box.

Modality can also be provided by using the ARIA attribute role="dialog". However, this moves some screen readers into Forms Mode and this means that non-form content is not announced by the screen reader.


Ideally the dialog box content starts with a level 1 heading. Using a level 1 heading signals that this content differs from the main page content. A level 1 heading also allows for more nested heading levels in the dialog content.

For sighted users it is very clear where the dialog starts and ends. Therefore the "Dialog start" and "Dialog end" messages are included for the benefit of screen reader users. These messages also serve as keyboard sentinels that keep the keyboard focus inside the dialog box. In some combinations of screen readers and browsers it might be possible for the user to navigate out of the dialog using Arrow Keys or other navigation keys. However, the user knows that a light box is there so it is unlikely that the users would choose to ignore the dialog.

The hidden text in the dialog is hidden using off-left positioning. Using a CSS clip to hide the text would not work for VoiceOver if you are moving focus to the text.

A function to be called before the dialog box opens (e.g. to populate the content) can be included as a third argument to the dialog box function. A function to be executed if the dialog box Close button is clicked can be included as a fourth argument.

Terms of Use

Developed by Pierre Frederiksen. Pierre is a Digital Access Specialist at Vision Australia

This software is being provided "as is", without any express or implied warranty. In particular, Vision Australia does not make any representation or warranty of any kind concerning the reliability, quality, or merchantability of this software or its fitness for any particular purpose. additionally, Vision Australia does not guarantee that use of this software will ensure the accessibility of your web content or that your web content will comply with any specific web accessibility standard.

Creative commons licence - logo
This work is licensed under a Creative Commons License

Print Print larger font