Dialog and Alertdialog (<dialog>)
When To Use
- For information that
- For important information that requires the user‘s immediate attention you can additionally use role="alertdialog" on the <dialog> element. 1
Rules
- The <dialog> element had and still has some issues that prevented the element from being the goto element when creating a dialog or alertdialog. This is slowly changing through changes in 2022 and 2023. 6
- If you have no need to cater to older browser versions or have very specific requirements, it may be beneficial to consider utilizing the <dialog> element instead of the dialog or alertdialog roles. Doing so would result in a greater amount of default behavior being implemented without the need for further customization (refer to the requirements listed below). 6
- Whether you use the <dialog> element or the dialog or alertdialog roles, make sure that your dialog satisfies these requirements:
- Ensure that there is at least one element that can receive focus included within. 2
- For dialogs: Set the value of aria-modal based on whether or not the content outside the Sidebar should be clickable. If the content outside the Sidebar should not be clickable, ensure that this is set. 1
- For alertdialogs: Set aria-modal (mandatory). Make sure the outside content is not clickable. 3
- Give the dialog an accessible name, for example by using aria-labelledby. 3 2
- Associate any visible text explanation to the dialog element using aria-describedby, for screen readers to announce the explanation when the dialog opens. Otherwise this explanation could be missed. 8
- Focus the default control inside the dialog box when it appears on the screen using the autofocus attribute with <dialog> elements. 1
- When the dialog is closed, restore the keyboard focus to either its previous position before the dialog appeared or to the beginning of the page. 2
- Modal dialogs should have a tab order that wraps, meaning that when the user tabs through the focusable elements within the dialog, the focus will loop back to the first element once the last element has been reached. In essence, the tab order should be confined to the dialog itself. 2
- Modal dialogs should have the ability to be closed through various means, including clicking a close/cancel/confirmation button, clicking on the overlay, or by pressing the ESC key on the keyboard. 1
- Ensure that the dialog is correctly hidden to exclude the focusable elements inside it from the tabbing index. 5
- If applicable, use aria-controls on the button that manages the modal, setting the value to the ID of the modal it controls.
- If a button controls the modal, utilize aria-expanded and ensure that the value is updated dynamically to reflect the state of the Sidebar. 5
- Some usage notes specifically on the <dialog> element:
- <dialog> elements that are invoked using the showModal() method will automatically have aria-modal="true". In contrast, <dialog> elements that are invoked using the show() method, rendered using the open attribute, or changing the default display of a <dialog> will have aria-modal="false". 1
- If a <form> element has the attribute method="dialog" or if the button utilized to submit the form has formmethod="dialog" set, it can close a <dialog>. 1
- When displaying a <dialog> using HTMLDialogElement.showModal(), the backdrop displayed behind it can be styled using the ::backdrop CSS pseudo-element. 1
Sources
- MDN: <dialog>: The Dialog element by Mozilla contributors is licensed under CC-BY-SA 2.5
- MDN: ARIA: dialog role by Mozilla contributors is licensed under CC-BY-SA 2.5
- MDN: ARIA: alertdialog role by Mozilla contributors is licensed under CC-BY-SA 2.5
- MDN: aria-expanded by Mozilla contributors is licensed under CC-BY-SA 2.5
- Scott Ohara: Use the dialog element (reasonably) by Scott Ohara
- HTML Spec: Living Standard, 4.11 Interactive elements, dialog is licensed under Creative Commons Attribution 4.0 International License
- TPGi: Describing aria-describedby by Scott Ohara © TPGi – a Vispero™ Company