From d9c56ea1910fe2b4e1ae1e1415c80e897f7b2c17 Mon Sep 17 00:00:00 2001 From: Matt Leathes Date: Mon, 14 Sep 2026 11:00:00 +0100 Subject: [PATCH 1/2] docs: correct aria-describedby guidance in Accessibility section ReactTooltip automatically adds its id to the active anchor's aria-describedby while the tooltip is shown and removes it on close, so the docs should not tell users to set the attribute manually. A static attribute also references the tooltip element before it is rendered (it is only added to the DOM once the tooltip opens). Rewrite the "Associating the anchor and tooltip" section to describe the automatic behaviour, and drop the manual aria-describedby from the combined example. --- docs/docs/accessibility.mdx | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/docs/docs/accessibility.mdx b/docs/docs/accessibility.mdx index 455f0676..c52270f1 100644 --- a/docs/docs/accessibility.mdx +++ b/docs/docs/accessibility.mdx @@ -92,37 +92,33 @@ Prefer a natively interactive element when the anchor is meant to be interacted ## Associating the anchor and tooltip (1.3.1) -So screen readers announce the tooltip content when the anchor is focused, add an `aria-describedby` attribute to the anchor referencing the tooltip's `id`. +This one is handled for you. While the tooltip is open, ReactTooltip adds its `id` to the active anchor's `aria-describedby` attribute (merging with any values already there), and removes it again when the tooltip closes. This is what lets screen readers announce the tooltip content when the anchor is focused. ```jsx - + ``` +:::caution + +Don't add `aria-describedby` to the anchor yourself. ReactTooltip manages it automatically, and a static attribute would point at the tooltip element even before it has been rendered (the tooltip is only added to the DOM once it opens). + +::: + :::info -ReactTooltip renders the tooltip element with `role="tooltip"`, so pairing it with `aria-describedby` gives assistive technologies the expected semantics. +ReactTooltip also renders the tooltip element with `role="tooltip"`, so the automatic association gives assistive technologies the expected semantics. ::: ## Putting it all together -This example combines all of the above: a keyboard-focusable anchor, associated with the tooltip via `aria-describedby`, whose content is reachable (`clickable`) and can be dismissed with Esc (`globalCloseEvents`). +This example combines all of the above: a keyboard-focusable anchor whose content is reachable (`clickable`) and can be dismissed with Esc (`globalCloseEvents`). ReactTooltip adds the `aria-describedby` association automatically while the tooltip is open. ```jsx import { Tooltip } from 'react-tooltip' - + - ◕‿‿◕ + ◕‿‿◕ Date: Mon, 14 Sep 2026 11:43:31 +0100 Subject: [PATCH 2/2] Minor amend as per coderabbitai suggestion --- docs/docs/accessibility.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/accessibility.mdx b/docs/docs/accessibility.mdx index c52270f1..a00e3995 100644 --- a/docs/docs/accessibility.mdx +++ b/docs/docs/accessibility.mdx @@ -101,7 +101,7 @@ This one is handled for you. While the tooltip is open, ReactTooltip adds its `i :::caution -Don't add `aria-describedby` to the anchor yourself. ReactTooltip manages it automatically, and a static attribute would point at the tooltip element even before it has been rendered (the tooltip is only added to the DOM once it opens). +Don't add the tooltip's `id` to the anchor's `aria-describedby` yourself. ReactTooltip manages it automatically, and a static attribute would point at the tooltip element even before it has been rendered (the tooltip is only added to the DOM once it opens). :::