Migrating to v7
- No more support for the
- No more usage of the
- Different expected markup
- More flexible position in the DOM
The support for the native
<dialog> HTML element has been discontinued. The rational behind this choice is explained more in detail in the page about the
Before migrating to v7, it is recommended you update your usage to no longer use the
<dialog> element as this will make the actual migration easier. To do so, replace any usage of the
<dialog> element with a
+ <div role="dialog">
The styles will also need to be updated, as you will no longer benefit from the native display handling from the
<dialog> element. Refer to the styling section and the demo for a set of styles to get you started.
Because the support for the
<dialog> element is being discontinued, the
open HTML attribute is no longer applied to the dialog. It is also not read to initialize the dialog in the right state, so it is no longer possible to start with a dialog open by default (which was a bad practice anyway).
The main difference between v6 and v7 is that a lot of the logic moved onto the container instead of the dialog itself.
aria-labelledbyattribute move from the former dialog element (or its
<div>equivalent) to the container.
- If wanting an alert dialog, the
role="alertdialog"attribute should be applied to the container.
- The backdrop no longers needs the
- The dialog element itself no longer exists. Its inner
role="document"are the new dialog. This is what should be styled as such.
- <div role="dialog" aria-labelledby="your-dialog-title-id">
<button type="button" data-a11y-dialog-hide aria-label="Close dialog">
<h1 id="your-dialog-title-id">Your dialog title</h1>
<!-- Your content here -->
data-a11y-dialog attribute for automatic instantiation on script load, its value is now the unique name for the dialog, just like an
Up to version 6, the dialog container needed to be somewhat close to the root of the document, fully separated from the main content container, so these two can have their
aria-hidden attribute toggled on and off as the dialog is being interacted with. This is no longer the case in v7, as the
aria-modal="true" on the dialog attribute replaces the use of
aria-hidden="true" on the main content container.
In turns, this means the dialog container can be rendered pretty much anywhere provided it never lives within an element with the
aria-hidden="true" attribute. It can be deeply nested within the DOM (although not recommended as it could increase risks of something going wrong), and things would work all the same.