[Tooltip] Trigger does not set aria-describedby

[mathias-falkenberg]

Feature request

Summary

BaseUI’s Tooltip component currently lacks a built-in way to properly associate tooltips with their trigger elements using aria-describedby. This feature would improve accessibility by ensuring that assistive technologies, such as screen readers, can properly announce tooltips as descriptions for their related elements.

Examples in other libraries

MUI Tooltip
React Aria Tooltip

Motivation

1. Improved Accessibility – Associating tooltips with their trigger elements using aria-describedby ensures that users relying on screen readers receive the tooltip information when focusing on the element.
2. Better Compliance with ARIA Practices – The W3C ARIA Authoring Practices Guide (APG) suggests linking tooltips to their trigger elements to provide clear context.
3. Consistency Across UI Libraries – Other popular component libraries, like MUI and React Aria, follow this practice, making it a valuable enhancement for BaseUI to maintain parity.
4. Improved Developer Experience – Developers would have an out-of-the-box solution to make tooltips more accessible, reducing the need for manual workarounds.

[mj12albert]

@atomiks We're not intentionally leaving out aria-describedby right?
I remember we heavily discussed the verbosity of announcing these as it relates to the length of the text

[atomiks]

We intentionally made Tooltip visual-only, as in most cases it's used as a visual label for the trigger (often an icon button). An accessible name (e.g. via aria-label) is preferred to communicate the same information for screen readers as the tooltip does for sighted users — aria-describedby repeats the accessible name twice when announced in this use case

There are cases where the tooltip offers additional information different from the accessible name though, where it could be useful. GitHub has a few examples:

The issue is differentiating when it's a label vs. when it's really a description to use aria-describedby

[mathias-falkenberg]

It seems to be a very common pattern that most other libraries support.
It's even stated in the WAI ARIA Tooltip pattern

I think the use-case of tooltips providing more information for an element (as described in the pattern above) is much more widespread.
I kind of see the issue with icon buttons announcing repeated labels. However, when the tooltip doesn't link its content to the trigger, that duplication just happens in code as you then need to provide the label both as an aria-label for the element and as content of the tooltip. They may even differ, which would be a potential a11y issue. Imagine applying proper translations to the tooltip but not the aria-label.

MUI provides a prop to specifically define whether the tooltip is applied as description (title) to the element or not.

[colmtuite]

Another issue is the lack of touch support. Using tooltips to provide important information about an interactive element is problematic, because they don't work on touch devices. It seems less problematic to relegate tooltips to being strictly used for displaying information that is not important.

[atomiks]

I think the use-case of tooltips providing more information for an element (as described in the pattern above) is much more widespread.

The most common use case for tooltips is visually labelling an icon button rather than providing 'extended' information about something that is already labelled/has button text.

However, when the tooltip doesn't link its content to the trigger, that duplication just happens in code as you then need to provide the label both as an aria-label for the element and as content of the tooltip.

It's because of touch input not showing tooltips that aria-label is preferred as the accessible name, instead of relying on aria-labelledby to make the tooltip act as the label source (since it doesn't show at all for that modality). Material UI's tooltip API makes applying the title="..." content as the aria-label="..." on the trigger for you automatically straightforward compared to our separate Tooltip.Popup API. You can create your own Tooltip component API wrapper that does this easily, though.

Agree with @colmtuite that tooltips should only display non-critical information and not be used as the primary labeling method due to touch input. We have a PR to add guidelines for Tooltip: #1356. If your tooltip is acting as 'extended' information (a real description, not a label) then you should probably be using a Popover instead that is on a button next to the interactive tool. Touch users can't see that information at all otherwise.

---

I personally think a type prop or similar to add role="tooltip" + aria-describedby when the tooltip is offering additional information (e.g. like the GitHub label screenshot above) to increase accessibility for keyboard screen reader usage is fine, but shouldn't be the default. Also note that the WAI-ARIA authoring practices is a guide, not a strict spec. We follow where it makes sense and make our own decisions otherwise (we do need to improve documentation when it deviates, though)

[colmtuite]

Can merge this. We'll loop back around later and fix it up when we get callouts etc. in