fix: a11y on interactive elements with tooltip with sr-only element

Author: HedwigJDoets

packages/pluggableWidgets/tooltip-web/CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Fixed
+
+- We fixed an accessibility issue where tooltip content was not announced by screen readers. Tooltip text is now immediately accessible when focusing or hovering over trigger elements through the use of `aria-describedby` pointing to always-present sr-only content.
+
 ## [1.5.1] - 2026-02-10
 
 ### Added

packages/pluggableWidgets/tooltip-web/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@mendix/tooltip-web",
     "widgetName": "Tooltip",
-    "version": "1.5.1",
+    "version": "1.5.2",
     "description": "Shows a value inside a colored tooltip or label",
     "copyright": "© Mendix Technology BV 2025. All rights reserved.",
     "license": "Apache-2.0",

packages/pluggableWidgets/tooltip-web/src/components/Tooltip.tsx

@@ -1,6 +1,6 @@
 import { Placement } from "@floating-ui/react";
 import classNames from "classnames";
-import { CSSProperties, ReactElement, ReactNode, useState } from "react";
+import { CSSProperties, ReactElement, ReactNode, useCallback, useEffect, useId, useRef, useState } from "react";
 import { OpenOnEnum, RenderMethodEnum } from "../../typings/TooltipProps";
 import { useFloatingUI } from "../utils/useFloatingUI";
 
@@ -22,6 +22,10 @@ export const Tooltip = (props: TooltipProps): ReactElement => {
     const { trigger, htmlMessage, textMessage, openOn, position, preview, renderMethod } = props;
     const [showTooltip, setShowTooltip] = useState(preview ?? false);
     const [arrowElement, setArrowElement] = useState<HTMLDivElement | null>(null);
+    const contentId = useId();
+    const hasTooltipContent = !!(textMessage || htmlMessage);
+    const triggerWrapperRef = useRef<HTMLDivElement>(null);
+
     const { arrowStyles, blurFocusEvents, floatingStyles, getFloatingProps, getReferenceProps, refs, staticSide } =
         useFloatingUI({
             position,
@@ -31,18 +35,60 @@ export const Tooltip = (props: TooltipProps): ReactElement => {
             openOn
         });
 
+    // Apply aria-describedby to all focusable elements inside the trigger wrapper
+    useEffect(() => {
+        if (!hasTooltipContent || !triggerWrapperRef.current) {
+            return;
+        }
+
+        // Find all focusable elements (button, a, input, select, textarea, etc.)
+        const focusableElements = triggerWrapperRef.current.querySelectorAll<HTMLElement>(
+            'button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+        );
+
+        if (focusableElements.length > 0) {
+            focusableElements.forEach(element => {
+                element.setAttribute("aria-describedby", contentId);
+            });
+
+            return () => {
+                focusableElements.forEach(element => {
+                    element.removeAttribute("aria-describedby");
+                });
+            };
+        }
+    }, [hasTooltipContent, contentId]);
+
+    // Merge our ref with floating-ui's ref
+    const setTriggerRef = useCallback(
+        (node: HTMLDivElement | null) => {
+            triggerWrapperRef.current = node;
+            if (refs?.setReference) {
+                refs.setReference(node);
+            }
+        },
+        [refs]
+    );
+
     return (
         <div className={classNames(props.class, "widget-tooltip", `widget-tooltip-${position}`)}>
             <div
                 className="widget-tooltip-trigger"
-                ref={refs?.setReference}
+                ref={setTriggerRef}
                 {...(preview
                     ? undefined
                     : getReferenceProps?.({ ...(openOn === "hoverFocus" && !preview ? blurFocusEvents : undefined) }))}
             >
                 {trigger}
             </div>
-            {showTooltip && (textMessage || htmlMessage) ? (
+            {/* Hidden content for screen readers - always in DOM, only accessible via aria-describedby */}
+            {hasTooltipContent && (
+                <div id={contentId} className="sr-only" aria-hidden="true">
+                    {renderMethod === "text" ? textMessage : htmlMessage}
+                </div>
+            )}
+            {/* Visible content for sighted users */}
+            {showTooltip && hasTooltipContent ? (
                 <div
                     className="widget-tooltip-content"
                     ref={refs?.setFloating}

packages/pluggableWidgets/tooltip-web/src/components/__tests__/Tooltip.spec.tsx

@@ -141,7 +141,7 @@ describe("Tooltip", () => {
         const triggerElement = screen.getByTestId("tooltip-trigger");
         await user.click(triggerElement);
 
-        expect(screen.queryByText("Simple Tooltip")).toBeInTheDocument();
+        expect(screen.queryByRole("tooltip")).toHaveTextContent("Simple Tooltip");
     });
 
     it("close onOutsideClick if tooltip is visible", async () => {
@@ -154,4 +154,95 @@ describe("Tooltip", () => {
         await user.click(document.body);
         expect(screen.queryByRole("tooltip")).toBeNull();
     });
+
+    describe("accessibility", () => {
+        it("adds aria-describedby to trigger element", () => {
+            render(<Tooltip {...defaultTooltipProps} />);
+            const triggerElement = screen.getByTestId("tooltip-trigger");
+
+            expect(triggerElement).toHaveAttribute("aria-describedby");
+        });
+
+        it("renders sr-only content for screen readers before tooltip is shown", () => {
+            render(<Tooltip {...defaultTooltipProps} />);
+            const srOnlyContent = document.querySelector(".sr-only");
+
+            expect(srOnlyContent).toBeInTheDocument();
+            expect(srOnlyContent).toHaveTextContent(defaultTooltipProps.textMessage as string);
+        });
+
+        it("sr-only content is always in DOM even when tooltip is not visible", () => {
+            render(<Tooltip {...defaultTooltipProps} openOn="click" />);
+            const srOnlyContent = document.querySelector(".sr-only");
+
+            // Content should exist before tooltip is shown
+            expect(srOnlyContent).toBeInTheDocument();
+            expect(screen.queryByRole("tooltip")).toBeNull();
+        });
+
+        it("sr-only content matches the text message", () => {
+            const customMessage = "Custom accessibility message";
+            render(<Tooltip {...defaultTooltipProps} textMessage={customMessage} />);
+            const srOnlyContent = document.querySelector(".sr-only");
+
+            expect(srOnlyContent).toHaveTextContent(customMessage);
+        });
+
+        it("sr-only content matches the HTML message", () => {
+            const htmlContent = <div>Custom HTML Content</div>;
+            render(
+                <Tooltip
+                    {...defaultTooltipProps}
+                    renderMethod="custom"
+                    htmlMessage={htmlContent}
+                    textMessage={undefined}
+                />
+            );
+            const srOnlyContent = document.querySelector(".sr-only");
+
+            expect(srOnlyContent).toHaveTextContent("Custom HTML Content");
+        });
+
+        it("does not add aria-describedby when no tooltip content is provided", () => {
+            render(<Tooltip {...defaultTooltipProps} textMessage={undefined} htmlMessage={undefined} />);
+            const triggerElement = screen.getByTestId("tooltip-trigger");
+            const parentElement = triggerElement.parentElement;
+
+            expect(parentElement).not.toHaveAttribute("aria-describedby");
+        });
+
+        it("adds aria-describedby to all focusable elements in trigger", () => {
+            render(
+                <Tooltip
+                    {...defaultTooltipProps}
+                    trigger={
+                        <div>
+                            <button data-testid="button1">Button 1</button>
+                            <button data-testid="button2">Button 2</button>
+                            <a href="#" data-testid="link1">
+                                Link
+                            </a>
+                        </div>
+                    }
+                />
+            );
+
+            const button1 = screen.getByTestId("button1");
+            const button2 = screen.getByTestId("button2");
+            const link = screen.getByTestId("link1");
+
+            // All focusable elements should have aria-describedby
+            expect(button1).toHaveAttribute("aria-describedby");
+            expect(button2).toHaveAttribute("aria-describedby");
+            expect(link).toHaveAttribute("aria-describedby");
+
+            // All should point to the same sr-only content
+            const ariaDescribedBy1 = button1.getAttribute("aria-describedby");
+            const ariaDescribedBy2 = button2.getAttribute("aria-describedby");
+            const ariaDescribedBy3 = link.getAttribute("aria-describedby");
+
+            expect(ariaDescribedBy1).toBe(ariaDescribedBy2);
+            expect(ariaDescribedBy2).toBe(ariaDescribedBy3);
+        });
+    });
 });

packages/pluggableWidgets/tooltip-web/src/components/__tests__/__snapshots__/Tooltip.spec.tsx.snap

@@ -6,20 +6,28 @@ exports[`Tooltip render DOM structure 1`] = `
     class="widget-tooltip widget-tooltip-right"
   >
     <div
-      aria-describedby=":r0:"
+      aria-describedby=":r1:"
       class="widget-tooltip-trigger"
     >
       <div
+        aria-describedby=":r0:"
         data-testid="tooltip-trigger"
         tabindex="0"
       >
         Trigger
       </div>
     </div>
+    <div
+      aria-hidden="true"
+      class="sr-only"
+      id=":r0:"
+    >
+      Tooltip text
+    </div>
     <div
       class="widget-tooltip-content"
       data-floating-ui-focusable=""
-      id=":r0:"
+      id=":r1:"
       role="tooltip"
       style="position: fixed; left: 0px; top: 0px; transform: translate(0px, 0px);"
       tabindex="-1"

packages/pluggableWidgets/tooltip-web/src/package.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8" ?>
 <package xmlns="http://www.mendix.com/package/1.0/">
-    <clientModule name="Tooltip" version="1.5.1" xmlns="http://www.mendix.com/clientModule/1.0/">
+    <clientModule name="Tooltip" version="1.5.2" xmlns="http://www.mendix.com/clientModule/1.0/">
         <widgetFiles>
             <widgetFile path="Tooltip.xml" />
         </widgetFiles>

packages/pluggableWidgets/tooltip-web/src/ui/Tooltip.scss

@@ -4,6 +4,19 @@
     }
 }
 
+// Screen reader only - visually hidden but accessible to assistive technology
+.sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border-width: 0;
+}
+
 .widget-tooltip-content {
     color: #24276c;
     display: inline-block;