Nesting dialogs is a questionable design pattern that is not referenced anywhere in the HTML 5.2 Dialog specification. Therefore it is actively discouraged in favour of clearer interface design. That being said, it is supported by the library.
There is an example in the cypress/fixtures directory of the repository, as well as an associated test in cypress/integration. The original feature request by Renato de Leão remains in issue #80.
As outlined in the fixture file, it is important that the nested dialogs are actually nested in the HTML as well, otherwise this won’t work with VoiceOver on Safari. That’s because anything outside of an
aria-modal="true" container is considered “inert”, so nested dialogs need to live within one another like Russian dolls.
Pressing ESC or clicking the backdrop will only close the top-most dialog, while the other remain untouched. It essentially makes it possible to stack dialogs on top of each other, then closing them one at a time.
For this to work seamlessly, and because of an implementation detail, make sure to either rely on auto-instantiation (via the
data-a11y-dialog="…" attribute) or to pass
aria-modal="true" to the container manually (normally done by the library). These two methods are used to pick up only the direct “closers” (elements with the
data-a11y-dialog-hide attribute), and not the ones within nested dialogs.