[A11y]: WithTooltip is not accessible

[Sidnioulz]

Describe the bug

All components that use WithTooltip to produce a menu/listbox/popup with interactive components are inaccessible, because WithTooltip closes when attempting to focus into the menu. This is an implementation side effect of the "close on click outside" feature of the underlying library.

We need to switch to something else (react-aria could be a good fit? they have a hook specifically for this) so we can have close on click outside without this buggy behaviour.

Then, we also want to show tooltips on focus rather than just on hover (in most cases). This is necessary to provide the same level of information to users with motor disabilities.

Note: this issue isn't about making every use of tooltips WCAG compliant. Tooltips are often used as-in in Storybook when a listbox, menu or dialog role and related keyboard focus trapping should be implemented.

Reproduction link

yarn storybook:ui

Reproduction steps

1. Focus to a button that uses a tooltip for a menu
2. Try to get into the menu without using your mouse

System

n/a, 9.2.0 alpha

Additional context

No response

[dosubot]

This accessibility issue with WithTooltip is well-known and tracked by Storybook maintainers. The root cause is that WithTooltip (and related dropdowns) uses popper.js or react-popper-tooltip, which closes the popup when focus moves inside, preventing keyboard users from interacting with menus or popups. This is confirmed in the Accessibility Roadmap and several discussions (RFC on popper.js alternatives).

There is ongoing work to replace these components with more accessible solutions. Radix UI is currently the preferred direction for new components, with a new Select and IconButton rework in progress (PR #31702). React Aria and Floating UI were also considered, but Radix UI was found to be easier to use and style, and supports incremental adoption. You can see a detailed comparison and codesandbox examples in the RFC discussion.

There is no immediate fix in the latest Storybook release. For now, if you need accessible menus or popups, you can use Radix UI (docs) or React Aria (docs) directly in your project. These libraries handle keyboard navigation, focus trapping, and ARIA roles out of the box.

If you want to explore or contribute to a custom solution, WithTooltip is implemented as a wrapper around react-popper-tooltip, with the closeOnOutsideClick prop controlling its behavior (source). However, its design offers little flexibility for accessibility fixes without major changes.

You can follow progress and join the ongoing discussions in the Accessibility Roadmap and the RFC for popper.js alternatives. Let me know if you need more technical details or integration tips!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[Sidnioulz]

In consideration of the RFC:

Non-breaking a11y fixes

We may want to disable Popper's own closeOnOutsideClick and reimplement it with react-aria, so that it closes the popup on outside clicks or on focus outside the trigger and listbox (whereas popper seems to ignore focus within the listbox).

RE: react-aria, I would specifically use useInteractOutside for the lower-level tooltip primitive, though, and not useMenu. Our tooltip currently powers a wide range of features:

• actual tooltips
• just one/two menus throughout the UI (e.g. Storybook menu button top of the sidebar)
• many, many single-selection selects
• one multi-selection select

useMenu covers the least frequent use case. We may want to use it where needed.

Selects are in the process of receiving their own (internally made) component. I've decided to go for an internal implementation because it's how we can match the native behaviour of a HTML select with single selection and the more complex behaviour of a multi-select, alongside a "Reset options" feature we have in virtually all our selects. I also disagree with react-aria's decision to make disabled options non-focusable as this masks their existence from blind users. I have reported issues in Radix UI's own select implementation that haven't yet been answered.

Long-term future (SB10+)

I would like to look into a replacement, maybe starting with drastically simplifying the WithTooltip API so we have breathing room to replace Popper.

In particular, Popper's tooltips mess up with DOM structure more than I like, and cause some CSS flex alignment properties to break on components that use WithTooltip.

We would also want to separate the actual tooltip use case (progressive disclosure which we can handle with sr-only spans or aria-describedby attributes) from virtually all popup use cases: menu, listbox (for select/combobox), dialog (for dialogs, drawers) which may need kb interaction. This is because all the latter use cases need aria-haspopup defined on the trigger.

Viable replacements

It is unclear if Radix is actively maintained. Most of the team seem to have moved on to Base UI. There is a worrisome amount of unanswered issues on radix-ui/primitives.

react-aria is great, and has been consistently maintained by Adobe for so many years now. But it's much more low-level and handles less out of the box for us. We would be wise to use it for our internal use cases but if there actually was an accessible UI library out there, it would do more for us.