Modal a11y

[davidalvarezr]

Hi,

I have 2 questions related to the Modal component.
In the documentation example, I tells us to use <Dialog> inside the modal.

1. Why is it internally a <section role="dialog"> instead of a <dialog> markup ?
2. Why is there no aria-modal="true" attribute on it ?

[devongovett]

Now that <dialog> is widely supported across browsers (not the case when we first built React Aria), it's a common question why you might still use a JS library like React Aria. I'll try to document some of the reasons here.

Top layer

One of the main reasons that you might want to avoid <dialog> is actually also one of its main features: the top-layer. Native dialogs render in a special layer on top of all other content, regardless of the z-index. This is a benefit if your whole app and all of its dependencies are built with this in mind, but that's often not the case.

For example, you might use a third-party dependency for certain overlays, like embedded support chat widgets, onboarding tours, toasts, tooltips, etc. Additionally, browser extensions like password managers often add overlays to a page. If all of those also use native dialog/popovers in the top-layer, then everything works as expected. But if any of them are traditional JS overlays not in the top-layer, then those will always display behind the dialog. That can be problematic if users need to access those elements while dialogs are open.

Even if all of those did use the top-layer, the browser doesn't give any control over their stacking order. If you show a toast and then open a dialog, the dialog will be on top no matter what. If you want toasts to always be on top, you have to remove them from the DOM and re-add them whenever a new dialog opens, potentially losing state like focus/form input in the process.

In the future, perhaps most libraries will be updated to use the top-layer for all overlays and then this problem will reduced, but it's a bit of a chicken and egg issue right now.

The same reasoning also applies to aria-modal – this will hide all elements outside the modal from assistive technologies, but sometimes there are special cases like toasts that should be visible while dialogs are open. That's why we use inert to hide individual elements outside modals instead.

Animations

Another reason native dialogs might not be a good fit is if need entry or exit animations. transition-behavior: allow-discrete and @starting-style have made it simple to apply transitions to dialogs, but if you want the backdrop to transition as well then you're out of luck until the overlay property is widely supported, otherwise the dialog is immediately removed from the top layer without waiting for animations (this can also affect the z-index during transitions). Also if you need more complex animations such as @keyframes or using JS-driven libraries, then things get more complicated as well. This may improve in the future as well.

Preventing page scrolling

Most JS-based modal libraries prevent page scrolling while dialogs are open. Surprisingly, the native <dialog> element doesn't do this. If you open a <dialog>, it remains centered but the page behind it can still scroll. So this would still need to be implemented with JS if that behavior is desired (it's more complex than simply applying overflow: hidden, which doesn't work on iOS).

Focus behavior

Native <dialog> elements do not fully contain focus like JS-based modals do. They allow you to tab out of the dialog into the browser chrome, requiring users to tab through all of the elements of the browser chrome (address bar, toolbar buttons, etc.) before reaching the dialog again. There is debate in the accessibility community about this: the ARIA practices guide says that dialogs should entirely contain focus to help guide users, but the HTML spec disagrees (see w3c/aria-practices#1772).

Is <dialog> a good fit?

For simple applications and websites, <dialog> can work great. Especially if you control every component that will be used on the site and don't need to handle use-cases like third party toasts, or require browser extension interoperability, and you're ok with the native focus/scrolling/animation behavior. In this case, definitely consider using it instead of a library like React Aria. But many apps do have those requirements. Browser APIs will continue to improve and we will continue to re-evaluate as they do. In the meantime, continuing to use JS-based modals is required for these more complex use-cases and third party interoperability.

[davidalvarezr]

Thanks a lot for the explanation!