From f82638393fa6f42713fc6f3eb3cb6ed397ae8a10 Mon Sep 17 00:00:00 2001 From: Yordan Stoyanov Date: Wed, 18 Nov 2026 16:35:13 +0100 Subject: [PATCH 1/4] [WC-3677] Tooltip: document keyboard and screen reader behavior --- .../widgets/tooltip.md | 65 +++++++++++++++---- 1 file changed, 52 insertions(+), 13 deletions(-) diff --git a/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md b/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md index e51d63cd703..94b4d0316d0 100644 --- a/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md +++ b/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md @@ -13,11 +13,13 @@ You can use the [Tooltip](https://marketplace.mendix.com/link/component/119160) When placing the new Tooltip widget onto a page, use the composable region to place the content which will trigger the tooltip. You can freely model and combine widgets per your use case. +To make the tooltip available to keyboard and screen reader users, the trigger must contain at least one focusable widget, such as a button, a link, or an input widget. For more information, see the [Keyboard and Screen Reader Support](#keyboard-screen-reader) section below. + ### Limitations This widget is affected by the following limitation: -* On Safari, the on-hover tooltip may not work properly when used on a disabled element. If this issue occurs, please use a different web browser. +- On Safari, the on-hover tooltip may not work properly when used on a disabled element. If this issue occurs, please use a different web browser. ## Configuration @@ -27,8 +29,14 @@ Several options can be defined in the Tooltip widget. For more information, see For the sake of simplicity, there are two methods for creating a tooltip: -* **Text** (default) – this mode lets you can enter text with or without parameters to quickly implement a tooltip in your app -* **Custom** – enable this mode to freely design what will be shown in the tooltip such as the text, images, and widgets +- **Text** (default) – this mode lets you can enter text with or without parameters to quickly implement a tooltip in your app +- **Custom** – enable this mode to freely design what will be shown in the tooltip such as the text, images, and widgets + +If the tooltip has no content, it does not open. This happens, for example, when the text contains only spaces, or when all the widgets in the custom content are hidden. + +{{% alert color="info" %}} +From version 1.6.0, custom tooltip content loads together with the page instead of when the tooltip first opens. This lets screen readers announce the content. Data sources inside custom content, such as a data view or a list view, run when the page loads, even if the user never opens the tooltip. Avoid heavy data sources in tooltip content, because they can slow down page loading. +{{% /alert %}} ### Tooltip Position @@ -36,10 +44,10 @@ You can define how to position the tooltip in relation to the trigger element. **Tooltip Position** options are as follows: -* Top -* Left -* Bottom -* Right +- Top +- Left +- Bottom +- Right ### Arrow Position @@ -47,9 +55,9 @@ With the new Tooltip widget you also can define how to position the tooltip arro **Arrow Position** options are as follows: -* Start -* Center -* End +- Start +- Center +- End ### Open On @@ -57,10 +65,41 @@ This option defines how the tooltip will be triggered. **Open on** options are as follows: -* **Click** – triggered when the user clicks on the trigger content -* **Hover** – triggered when the user hovers the mouse over it -* **Hover and focus** – triggered in both cases described above +- **Hover,focus** (default) – triggered when the user hovers the mouse over the trigger content, and when a widget in the trigger receives keyboard focus +- **Hover** – triggered when the user hovers the mouse over the trigger content; keyboard focus does not open the tooltip +- **Click** – triggered when the user clicks on the trigger content, or presses Enter or Space on a button or link in the trigger + +From version 1.6.0, new Tooltip widgets use **Hover,focus** by default, so keyboard users can see the tooltip. Existing Tooltip widgets keep their current **Open on** setting when you update the widget. To make an existing tooltip available to keyboard users, change its **Open on** setting to **Hover,focus** or **Click**. {{% alert color="warning" %}} On mobile devices the **Hover** option will be triggered on touch. {{% /alert %}} + +## Keyboard and Screen Reader Support {#keyboard-screen-reader} + +The sections below describe how the Tooltip widget works with the keyboard and with screen readers. This behavior applies from version 1.6.0 of the widget. + +### Keyboard Support + +How the tooltip responds to the keyboard depends on the **Open on** setting: + +- **Hover,focus** + - The tooltip opens when a widget in the trigger receives focus, for example when the user presses Tab to move to a button. Focus stays on the trigger. + - With custom content, the user can press Tab to move focus from the trigger into the tooltip content. The tooltip stays open while focus is inside the trigger or the tooltip content. + - The tooltip closes when focus moves out of both the trigger and the tooltip content. +- **Hover** – the tooltip does not open on keyboard focus. +- **Click** + - Pressing Enter or Space on a button or link in the trigger opens the tooltip, and pressing it again closes the tooltip. This also works when the trigger is an action button, and the button's action still runs. + - Clicking in a text box or on a check box in the trigger opens the tooltip but does not close it. Typing in a text box does not open or close the tooltip. + - Moving focus to the trigger does not open the tooltip. + +In every mode, pressing Esc closes the tooltip. If focus is inside the custom tooltip content, focus returns to the trigger. + +### Screen Reader Support + +The tooltip content is linked as the description of every focusable widget in the trigger. When a screen reader user moves focus to one of these widgets, the screen reader announces the widget followed by the tooltip content, whether or not the tooltip is open. + +Keep the following in mind: + +- A trigger without a focusable widget gets no description, so screen reader users cannot reach the tooltip. Place a focusable widget, such as a button, in the trigger. +- When the tooltip has no content, the trigger gets no description. From f1379bd1b997aaa73daefdc636693b34cd969dce Mon Sep 17 00:00:00 2001 From: ConnorLand <47385345+ConnorLand@users.noreply.github.com> Date: Thu, 19 Nov 2026 13:13:01 +0100 Subject: [PATCH 2/4] Update tooltip.md --- .../marketplace/platform-supported-content/widgets/tooltip.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md b/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md index 94b4d0316d0..6dda4a02e0e 100644 --- a/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md +++ b/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md @@ -13,7 +13,7 @@ You can use the [Tooltip](https://marketplace.mendix.com/link/component/119160) When placing the new Tooltip widget onto a page, use the composable region to place the content which will trigger the tooltip. You can freely model and combine widgets per your use case. -To make the tooltip available to keyboard and screen reader users, the trigger must contain at least one focusable widget, such as a button, a link, or an input widget. For more information, see the [Keyboard and Screen Reader Support](#keyboard-screen-reader) section below. +To make the tooltip available to keyboard and screen reader users, the trigger must contain at least one focusable widget, such as a button, link, or an input widget. For more information, see the [Keyboard and Screen Reader Support](#keyboard-screen-reader) section below. ### Limitations From 0b3a952786d56a82067632f11352621e91d15431 Mon Sep 17 00:00:00 2001 From: ConnorLand <47385345+ConnorLand@users.noreply.github.com> Date: Thu, 19 Nov 2026 13:14:47 +0100 Subject: [PATCH 3/4] Update tooltip.md --- .../marketplace/platform-supported-content/widgets/tooltip.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md b/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md index 6dda4a02e0e..3ef39ef691b 100644 --- a/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md +++ b/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md @@ -35,7 +35,7 @@ For the sake of simplicity, there are two methods for creating a tooltip: If the tooltip has no content, it does not open. This happens, for example, when the text contains only spaces, or when all the widgets in the custom content are hidden. {{% alert color="info" %}} -From version 1.6.0, custom tooltip content loads together with the page instead of when the tooltip first opens. This lets screen readers announce the content. Data sources inside custom content, such as a data view or a list view, run when the page loads, even if the user never opens the tooltip. Avoid heavy data sources in tooltip content, because they can slow down page loading. +From version 1.6.0 and above, custom tooltip content loads together with the page instead of when the tooltip first opens. This allows screen readers to announce the content. Data sources inside custom content, such as a data view or a list view, run when the page loads even if the user never opens the tooltip. We recommend you avoid heavy data sources in tooltip content, because they can decrease page performance. {{% /alert %}} ### Tooltip Position From dd41979e452e9d7505cf8ba0f6f4102ed0a21f94 Mon Sep 17 00:00:00 2001 From: ConnorLand <47385345+ConnorLand@users.noreply.github.com> Date: Thu, 19 Nov 2026 13:15:47 +0100 Subject: [PATCH 4/4] Update tooltip.md --- .../marketplace/platform-supported-content/widgets/tooltip.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md b/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md index 3ef39ef691b..d691c8dcb0e 100644 --- a/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md +++ b/content/en/docs/marketplace/platform-supported-content/widgets/tooltip.md @@ -90,7 +90,7 @@ How the tooltip responds to the keyboard depends on the **Open on** setting: - **Hover** – the tooltip does not open on keyboard focus. - **Click** - Pressing Enter or Space on a button or link in the trigger opens the tooltip, and pressing it again closes the tooltip. This also works when the trigger is an action button, and the button's action still runs. - - Clicking in a text box or on a check box in the trigger opens the tooltip but does not close it. Typing in a text box does not open or close the tooltip. + - Clicking in a text box or on a checkbox in the trigger opens the tooltip but does not close it. Typing in a text box does not open or close the tooltip. - Moving focus to the trigger does not open the tooltip. In every mode, pressing Esc closes the tooltip. If focus is inside the custom tooltip content, focus returns to the trigger.