Skip to content

docs(ui5-link): clarify navigation vs. action usage and accessible role #14088

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
unazko merged 2 commits into from
Sep 29, 2026
Merged

docs(ui5-link): clarify navigation vs. action usage and accessible role #14088

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7ecd27c
docs(ui5-link): clarify navigation vs. action usage and accessible role
unazko Sep 24, 2026
48bda32
docs(ui5-link): clarify navigation vs. action usage and accessible role
unazko Sep 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion packages/main/src/Link.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,21 @@ type LinkAccessibilityAttributes = Pick<AccessibilityAttributes, "expanded" | "h
* anchor tag (`<a></a>`) 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. 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 browser handles navigation, 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 without `href` has
* no destination 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.
Expand Down Expand Up @@ -202,7 +217,7 @@ class Link extends UI5Element implements ITabbable {
/**
* Defines the ARIA role of the component.
*
* **Note:** Use the <code>LinkAccessibleRole.Button</code> role in cases when navigation is not expected to occur and the href property is not defined.
* **Note:** Set the role to <code>LinkAccessibleRole.Button</code> when the link triggers an action instead of navigating (when the <code>href</code> property is not defined). Otherwise, the component keeps the default <code>"Link"</code> role, and some screen readers (for example, JAWS in browse mode) cannot activate it, as a link with no <code>href</code> has no destination to navigate to.
* @default "Link"
* @public
* @since 1.9.0
Expand Down
Loading