React: Fix performance issue with useTopLayer in causing re-renders of all consumers on page whenever a single one changes

[rkoval]

Fixes #3630

---

First off, Headless UI is great!! I love that I have full control over the visual display of all components within. Thank you so much for your effort in creating and maintaining this!! 🙏

---

My understanding of the problem:

All of the current useOutsideClick components (i.e., Menu, Combobox, Dialog, Listbox, and Popover) rely on the underlying useIsTopLayer hook to know what position of the visual stack each component. As each component renders, they are pushed on top of this useIsTopLayer stack. This stack is then used to determine which component to dismiss when clicking off of the menu or pressing "Escape". This is explained better in this comment.

However, the problem is that each component gets pushed into the stack even if the menu is not being displayed on screen; it is the component trigger that determines what gets added or removed from the stack because it applies to the top-level component. For example, you still must render a top-level Popover component to wrap PopoverButton even PopoverPanel will not be visible until PopoverButton is interacted with. This becomes problematic because useOutsideClick uses the same bucket key internally for all components that consume it. That means that every time a consuming component renders, it causes the useIsTopLayer bucket to add/remove, which triggers re-renders from every component that uses useOutsideClick. If you have a lot of these components on screen at once (e.g., think having a table with context menus for each row), this can slow down page performance significantly, especially for lower end devices

My proposed solution:

For each of the consuming components, expose a outsideClickScope prop that will allow passing a scope down into useIsTopLayer so that each one has its own bucket/stack. If you have menus that require knowledge of other menus to be in the same stack for closing (e.g., a Listbox within a Dialog), you must pass in the same scope key for both components so that they know how to interact.

This solves our immediate problem, though it does not feel like the most elegant solution for the following reasons:

1. It doesn't completely solve the underlying re-render problem. There are legitimate use cases for components that have the same scope (e.g., again, components within a Dialog), so if you have many of those in the same scope, the same problem is still present.
2. For the components within a Dialog use case, you must have some context or mechanism that knows when you need to pass in a specific scope so that the outside click logic knows the order by which to hide the components.
3. I do not know the best way to document this. The existing code is "better" from a usability perspective given that users don't need to know about this internal implementation detail; though, the performance issue basically makes the component not practically usable in any products of remote scale.
4. I don't like the naming I used. I'm happy to change these names to whatever makes the most sense
5. It does nothing to address the Vue codebase, if the problem exists there. I have no experience with Vue, so I cannot help there

All of this said, this solution will solve all practical cases outside of the nested use case, and it's only one I can think of without a broader refactoring of how useOutsideClick/useIsTopLayer works. Being that I am a first time contributor to this codebase, I know that I do not have the context necessary to make such a sweeping change efficiently and effectively 😅.

If we want to hold on this PR for a broader/better solution to be implemented, I would love for it to at least be merged as undocumented so that immediate usage is unblocked, and we don't have to maintain our own fork.

I am open to thoughts for how best to proceed!

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
headlessui-react	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Mar 8, 2025 9:33pm
headlessui-vue	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Mar 8, 2025 9:33pm

[rkoval]

hey @RobinMalfait - i would love your thoughts here at your earliest convenience! this issue seems like this is related to this PR, so your guidance would be greatly appreciated

[RobinMalfait]

Hey!

Thanks for your work on this problem. I went with another solution implemented in #3722

I think the implementation where you can control the outsideClickScope seems more like a bandaid solution and you will run into this issue again.

What I ended up doing instead, is make sure that the hook only re-renders the component if the result actually changes. This is using a useSyncExternalStoreWithSelector hook and only if the state passed to the selector changes only then a re-render happens.

This means that only 2 components at most should re-render:

1. The one that was the top-most component, and isn't anymore
2. The component that is now the top-most component

All the other components were already in the isTopLayer === false state