From 7ecd27c7d0a7d837f2976faf0589ef4905b506c4 Mon Sep 17 00:00:00 2001 From: Boyan Rakilovski Date: Thu, 24 Sep 2026 12:08:34 +0300 Subject: [PATCH 1/2] docs(ui5-link): clarify navigation vs. action usage and accessible role **Issue** A link used to trigger an in-page action, left on the default "Link" role with no href, is not activated by some screen readers (e.g. JAWS in browse mode), because a link with no destination has nothing to navigate to. The docs did not surface the action use case, so developers could miss that accessibleRole="Button" is required for action-only links. **Solution** - Add a "Navigation vs. Action" section to the component overview: navigation -> set href; action -> set accessibleRole="Button". - Expand the accessibleRole property note to explain why the button role matters (screen-reader activation), not just when to use it. **Testing** Documentation-only change (JSDoc); no automated test applies. No runtime or API behavior changed. Fixes #14068 --- packages/main/src/Link.ts | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/packages/main/src/Link.ts b/packages/main/src/Link.ts index 7b11102b66828..2de738ead25b3 100644 --- a/packages/main/src/Link.ts +++ b/packages/main/src/Link.ts @@ -56,6 +56,21 @@ type LinkAccessibilityAttributes = Pick`) and opens the specified URL in the given target frame (`target` property). * To specify where the linked content is opened, you can use the `target` property. * + * ### Navigation vs. Action + * + * The `ui5-link` supports two distinct use cases, and choosing the right one is important for accessibility: + * + * - **Navigation** - set the `href` property (and optionally `target`). The component behaves as a + * standard anchor tag and the navigation is performed by the browser, which also enables native + * affordances such as open-in-new-tab, copy link, and hover preview. + * - **Action** - when the link triggers an in-page action (for example, opening a dialog) instead of + * navigating, leave `href` unset and set `accessibleRole` to `"Button"`. This exposes the component + * with a `button` role, which assistive technologies activate reliably. + * + * **Note:** A link that triggers an action but keeps the default `"Link"` role (with no `href`) cannot be + * activated by some screen readers, such as JAWS in browse mode, because a link with no destination has + * nothing to navigate to. Always set `accessibleRole="Button"` for action-only links. + * * ### Responsive behavior * * If there is not enough space, the text of the `ui5-link` becomes truncated. @@ -202,7 +217,7 @@ class Link extends UI5Element implements ITabbable { /** * Defines the ARIA role of the component. * - * **Note:** Use the LinkAccessibleRole.Button role in cases when navigation is not expected to occur and the href property is not defined. + * **Note:** Set the role to LinkAccessibleRole.Button when the link triggers an action instead of navigating, that is, when the href property is not defined. Otherwise the component keeps the default "Link" role, and some screen readers (for example, JAWS in browse mode) will not activate it, as a link with no href has no destination to navigate to. * @default "Link" * @public * @since 1.9.0 From 48bda325ccae5f890b796c6458d23103a5ea169c Mon Sep 17 00:00:00 2001 From: Boyan Rakilovski Date: Thu, 24 Sep 2026 17:27:44 +0300 Subject: [PATCH 2/2] docs(ui5-link): clarify navigation vs. action usage and accessible role --- packages/main/src/Link.ts | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/main/src/Link.ts b/packages/main/src/Link.ts index 2de738ead25b3..97ed465fedf87 100644 --- a/packages/main/src/Link.ts +++ b/packages/main/src/Link.ts @@ -58,18 +58,18 @@ type LinkAccessibilityAttributes = PickLinkAccessibleRole.Button when the link triggers an action instead of navigating, that is, when the href property is not defined. Otherwise the component keeps the default "Link" role, and some screen readers (for example, JAWS in browse mode) will not activate it, as a link with no href has no destination to navigate to. + * **Note:** Set the role to LinkAccessibleRole.Button when the link triggers an action instead of navigating (when the href property is not defined). Otherwise, the component keeps the default "Link" role, and some screen readers (for example, JAWS in browse mode) cannot activate it, as a link with no href has no destination to navigate to. * @default "Link" * @public * @since 1.9.0