[Bug]: Dialog: There are no focusable elements inside the <FocusTrap />

[Krystofee]

What package within Headless UI are you using?

@headlessui/react

What version of that package are you using?

1.0.0

What browser are you using?

Chrome

Reproduction repository

https://codesandbox.io/s/gallant-butterfly-wnxjb

Description

When there is no focusable element inside modal, it fails with error There are no focusable elements inside the <FocusTrap />. I don't know if it's a feature or a bug, but there isn't said in the documentation that Dialog must include at least one focusable element and I totally see a use-case when there are modals without any focusable element. I think it at least should fail with warning instead of fatal error.

Anyways I would like to thank you for the great job you all are doing with the tailwind ecosystem, we really appreciate your work!

[etc-tiago]

I believe it is purposeful, as there are specific cases that the modal needs to be displayed without a button or input.

If you need to display this modal and do not want the button/input appear, you can use it like this:

<button className="h-0 w-0 overflow-hidden"/>

But I strongly recommend to add at least one "close" button in case of usability or smaller screens, where the space of the overlay is not large enough to be clickable / touchable.

[Krystofee]

You got a point, but I think there are many valid usecases where there are no focusable elements and you don't want any, e. g.

• Loading contents of the Dialog - while it's loading, you probably render only spinner and nothing else and don't expect the Dialog to crash.
• Or you just want to show some Dialog to the users when they were locked out of their account and there is no action that thay can take within the app.

Even then, there is no big red caveat that this error will happen if you somewhat forget to render anything in the Dialog.

So I propose two ways out:

1. Dialog should not crash when there is no focusable element within.
2. Add some caveat to the docs that the Dialog will crash if rendered without any focusable elements.

If it was the second, then I think many users (including me) which are building internal set of components on top of headless ui will just insert the hidden focusable element to prevent Dialogs from crashing.

[trm217]

@Krystofee I 100% agree with your proposal, but I would add another change:

• There should be an option for the overlay to not close the modal on click. For example, in a loading-modal you wouldn't want the user to able to cancel the modal.

[Krystofee]

@trm217 this is doable by managing the state of the modal by yourself and handling Dialog onClose prop according to the loading state. I think that's not the problem of this issue and should be resolved in the discussions.

[trm217]

@Krystofee I'm aware of that, yet I believe that this would be a fitting change in regards to your above-mentioned proposed changes. Therefore if your proposed changes would be implemented, my proposal would make sense to implement as well since it goes hand in hand with others.

[barnabaskecskes]

I've got a TableFilters component and several actual filter components, for example an ApplicationFilter. I use the provide/inject API of Vue to register the filter components to the main component when created(), so they can interact with each other in order to set initial states from the query string, etc. For that to work, I had to set the Dialog not to be unmounted. Doing that I get the same error as above.

In my case, there are focusable components in the dialog - but as it's not rendered, those are not actually focusable. Does the FocusTrap check for a visible state before trying to actually focus?

UPDATE: I could get around the issue by setting the initialFocus to an arbitrary element of the DOM.

[Krystofee]

I think components that are not rendered are generally not focusable. That's not a feature of headless ui but general feature of browser.

And yeah, I was reading the source code and also noticed the hack with the initialFocus, but thats not a good API and this approach comes with caveats too.

I'm really interested in hearing a feedback from @RobinMalfait on this topic.

[adamwathan]

Hey! This isn't a bug, for accessibility reasons all modal dialogs must contain a focusable element. Worth reading:

https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal

If content is large enough that focusing the first interactive element could cause the beginning of content to scroll out of view, it is advisable to add tabindex=-1 to a static element at the top of the dialog, such as the dialog title or first paragraph, and initially focus that element.

If you are showing a loading state or similar, it seems like it would be acceptable to add tabindex="-1" to the loading area and focus that while the content loads in, then imperatively focus the element you want focused after loading is finished.

I don't think we have any plans to change the current behavior as a major goal of this project is to help people build accessible interfaces, but I'll leave this open unless @RobinMalfait has anything he would like to add.

[barnabaskecskes]

Thinking about it (every since), also reading up on this (thanks, @adamwathan), the Dialog might not be appropriate for my use case anyway.

TL;DR I'll leave a simplified example below, just in case somebody tries to abuse the Dialog just as I did.

<TableLayout>
    <TableFilters>
        <FilterConfiguration />
        <Dialog>
            <FilterA />
            <FilterB />
        </Dialog>
    </TableFilters>
</TableLayout>

The TableFilters component deals with managing the URL as the actual filters are applied. The FilterConfiguration is a textual representation of the filters set for the table. It uses the provide/inject API and the filters register themselves on created/mounted, so the FilterConfiguration can display the initial filters set should they come from the URL. For that, the Dialog has to be unmounted=false, which in turn causes the error.

Again, thinking this through, the Dialog is not the solution - the more I think about it, the more it seems that Popover is much more appropriate for this thing. I'll convert to that instead.

Thanks for the help!

[Krystofee]

@adamwathan what you are saying is that "There should be at least one focusable element in the modal." and I agree with that.

What I don't agree with, is the way it's enforced. You cannot throw an error because of accessibility reasons. By doing that, you are putting accessibility before reliability, which means that you will have fully accessible software which will crash all the time or not even boot. I believe software must be fully reliable before one start dealing with accessibility.

I don't understand the reasons behind this decision, and it's also because I haven't seen any UI framework enforcing accessibility via throwing errors. And going even further, if I notice that some of the hundreds of dependencies in our project throws an exception, I just go to the project github and report a bug, because most of the time it's a bug.

And even if it was intentional, it's not documented and users will have to read through the code and will eventually create a Bug report like this one.

[hailwood]

This is also an issue with hmr (react) which I believe is a bug.

When I have a dialog, whenever I have a dialog open and change something so it has to reload (e.g. text in the dialog content) I always get There are no focusable elements inside the <FocusTrap />

It seems to be related to initialFocus e.g. if I have

<Dialog>
    <input />
</Dialog>

Then on the hmr reload it will fail, but if I have

<Dialog initialFocus={inputRef}>
    <input ref={inputRef} />
</Dialog>

Then it will work as expected

[realStandal]

I'm running into this error when using the Dialog. It's occurring while using the component in Storybook. I'm not sure if it's related to the above HMR issue, I can create a new issue if need be. I'm using the React Dialog component.

The error occurs while trying to control the component using Storybooks controls, where I can click a button to toggle a true/fale prop passed to the Dialog. Changing this value will throw the error, the component loads fine at first.

Controlling the Dialog from within the story (having a button setState to show/hide it) also throws.

If I manually pass the ref, it works as expected.

It works as expected in my Redwood app, without the need to explicitly define the initial ref.

Edit: After putting more time towards the bug, and not what I was trying to accomplish at the time, I'm able to use the Dialog within a Story and control it with Storybook's controls by creating an intermediary component that handles the Dialog's state; no explicit passing of a ref involved. I've had to do the same thing before for other components which have a controlled state, so it's possible it's just a hiccup with Storybook/how I've or the framework I'm using has set it up. Again, it's not the first time Storybook hasn't played well with a component, Transition has a hard time being controlled via it and components I create/have used from other libraries.