feat: add HasAriaDescription interface by vursen · Pull Request #25117 · vaadin/flow

vursen · 2026-08-03T09:21:24Z

Description

Adds a HasAriaDescription mixin interface for setting the accessible description of a component, following the HasAriaLabel pattern:

setAriaDescription(String) / getAriaDescription() for the aria-description attribute
setAriaDescribedBy(String) / getAriaDescribedBy() for the aria-describedby attribute
setAriaDescribedBy(Component) for referencing a description component directly, generating an id for it lazily when needed (same mechanism as setAriaLabelledBy(Component))

Also adds the aria-description and aria-describedby attribute name constants to ElementConstants.

Part of vaadin/web-components#11975

Type of change

Feature

Adds a mixin interface for setting the accessible description of a component via the aria-description and aria-describedby attributes, following the HasAriaLabel pattern. The aria-describedby value can also be set by referencing another component, generating an id for it lazily when needed. Unlike HasAriaLabel, the getters return the plain attribute value or null instead of Optional, as no obvious reason was found to support Optional. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

aria-describedby also works with hidden elements, so the guidance to choose between the attributes based on visibility was misleading. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

github-actions · 2026-08-03T09:57:14Z

Test Results

1 449 files +1 1 450 suites +1 1h 27m 44s ⏱️ + 1m 33s
10 393 tests +5 10 326 ✅ +5 67 💤 ±0 0 ❌ ±0
10 829 runs +5 10 761 ✅ +5 68 💤 ±0 0 ❌ ±0

Results for commit fffde7b. ± Comparison against base commit ab58985.

♻️ This comment has been updated with latest results.

vursen · 2026-08-03T10:35:47Z

+     *
+     * @return the aria-description or {@code null} if none has been set
+     */
+    default String getAriaDescription() {


The getters return the plain attribute value or null, which diverges from the Optional<String> getters in HasAriaLabel. Why Optional was chosen there isn't obvious to me.

#12126 (comment)

I don't have strong opinions on that, but it is definitely weird to have a different return type for a similar use case.

OK, changed the getters to return Optional.

mcollovati · 2026-08-03T11:25:24Z

+        }
+        ComponentUtil.resolveOrGenerateIdLater(getElement(),
+                descriptionComponent, "ariadescribedby-",
+                this::setAriaDescribedBy);


The utility class takes a Consumer<String> that is actually wrong, since the instance is then captured by other lambdas stored in the VaadinSession.
This should be fixed in ComponentUtil.resolveOrGenerateIdLater, maybe in a separated PR.

Created #25118

mcollovati · 2026-08-03T11:30:59Z

+        ComponentUtil.resolveOrGenerateIdLater(getElement(),
+                descriptionComponent, "ariadescribedby-",
+                this::setAriaDescribedBy);


If I call this method and then call setAriaDescribedBy(String), the former will anyway override the latter, because the beforeClientResponse gets not cancelled.
I guess this is a general issue for all components using the ComponentUtil.resolveOrGenerateIdLater method.

Right. I guess we could also sidestep this by setting aria-describedby inside a beforeClientResponse callback, but I'm not sure deferring all the work to these callbacks is a good approach in general.

Let's keep this also in a separate PR (#25119)

We can merge this PR, but then it should be "fixed" in #25127.
Or the other way around, we first look at #25127 and the update this PR.
But if this is block flow-components developments, let's just merge this first.

I'd appreciate it if this one could be merged first, so I can continue working on the Flow components.

Aligns the getters with the Optional<String> return type used by HasAriaLabel. Also adds a test for setting the description component id after calling setAriaDescribedBy(Component) and switches the test class to qualified Assertions calls. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Addresses review feedback asking for attribute purpose references at the class level. The class javadoc now explains the accessibility purpose and links the setter methods, while attribute names and spec links stay in the method javadocs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

sonarqubecloud · 2026-08-04T07:01:31Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
90.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

knoobie · 2026-08-04T19:43:32Z

Asking for a friend.. if no component supports setAriaDescription - why was it added in the first place? Wouldn't it be more sane to have two interfaces, one for HasAriaDescription and one for HasAriaDescribedBy so that the fields only implement the later (which they clearly support?)

vursen · 2026-08-05T06:04:22Z

Asking for a friend.. if no component supports setAriaDescription - why was it added in the first place? Wouldn't it be more sane to have two interfaces, one for HasAriaDescription and one for HasAriaDescribedBy so that the fields only implement the later (which they clearly support?)

Huh, that's actually a good point... I think I'm going to open a PR :) thanks!

vursen · 2026-08-05T06:18:07Z

Huh, that's actually a good point... I think I'm going to open a PR :) thanks!

On the other hand, these two methods really go hand in hand, and they even interact: one of them can end up shadowing the other. Also, field components could technically support aria-description by creating an invisible node with that text and pointing to it via aria-describedby. It's just out of scope for now.

I'll discuss this with the team.

Removes setAriaDescription(String) and getAriaDescription() from the HasAriaDescription interface (added in #25117, unreleased) because assistive technology support for the aria-description attribute is still not ideal. The API can be reconsidered later once support improves. Also removes the now-unused ARIA_DESCRIPTION_ATTRIBUTE_NAME constant from ElementConstants. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

vursen · 2026-08-05T07:34:45Z

I discussed this with the team, and we decided to drop setAriaDescription from HasAriaDescription for now, since its support isn't ideal anyway. We can come back to this later.

knoobie · 2026-08-05T07:36:32Z

Thanks for checking with the team!

…#25135) ## Description Removes `setAriaDescription(String)` and `getAriaDescription()` from the `HasAriaDescription` interface (added in vaadin#25117, unreleased) because assistive technology support for the `aria-description` attribute is still not ideal. The API can be reconsidered later once support improves. Part of vaadin/web-components#11975 Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

vaadin-bot · 2026-08-10T09:42:49Z

This ticket/PR has been released with Vaadin 25.3.0-alpha8.

## Summary Vaadin 25.3 added two accessibility mixin interfaces that the *Mixin Interfaces* page doesn't list, even though that list is where a reader looks for what a component can implement: - `vaadin/flow#24782` — `HasAriaRole` (`setAriaRole()` / `getAriaRole()`) - `vaadin/flow#25117`, narrowed by `vaadin/flow#25135` — `HasAriaDescription` (`setAriaDescribedBy(String)`, `setAriaDescribedBy(Component)`, `getAriaDescribedBy()`) ## What changed In `articles/flow/component-internals/mixins.adoc`, under *Other Useful Mixin Interfaces*: - added `HasAriaDescription` — the accessible description is set by referencing existing elements with `setAriaDescribedBy()`, and supplements the accessible name - added `HasAriaRole` — sets the `role` attribute on the root element by default, and the methods can be overridden to target another element - fixed the name of `HasAriaLabel`, which the same list spelled `HasArialLabel` (the only occurrence in the docs) ## How to test Documentation only, no code examples added, so nothing to compile. The descriptions match the javadoc of `HasAriaRole` and `HasAriaDescription` in 25.3. Co-authored-by: totally-not-ai[bot] <290682512+totally-not-ai[bot]@users.noreply.github.com>

vursen and others added 9 commits August 3, 2026 13:20

docs: add @SInCE 25.3 to HasAriaDescription and new constants

f9115ca

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: state attribute precedence instead of prescribing usage

a40d87e

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: move spec links from class-level to method javadocs

996d0bc

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: move spec links to method javadocs, drop bold tags

b305eaa

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: polish HasAriaDescription javadoc wording

284b35b

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: drop visible-text guidance from HasAriaDescription javadoc

530f112

aria-describedby also works with hidden elements, so the guidance to choose between the attributes based on visibility was misleading. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: simplify setAriaDescribedBy(Component) javadoc

a39ac87

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: rewrite HasAriaDescription class javadoc

5169c1e

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

vursen marked this pull request as ready for review August 3, 2026 09:42

github-actions Bot added the +0.1.0 label Aug 3, 2026

vursen requested review from mcollovati and tltv August 3, 2026 10:18

vursen commented Aug 3, 2026

View reviewed changes

vursen mentioned this pull request Aug 3, 2026

feat: add HasAriaDescription to field components vaadin/flow-components#9811

Merged

mcollovati reviewed Aug 3, 2026

View reviewed changes

Comment thread flow-server/src/test/java/com/vaadin/flow/component/HasAriaDescriptionTest.java Resolved

mcollovati reviewed Aug 3, 2026

View reviewed changes

Comment thread flow-server/src/main/java/com/vaadin/flow/component/HasAriaDescription.java Resolved

vursen and others added 5 commits August 3, 2026 19:11

docs: clarify referenced element wording in class javadoc

fc29464

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

simplify tests

c7ec269

docs: improve HasAriaDescription javadocs

fffde7b

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mcollovati approved these changes Aug 4, 2026

View reviewed changes

mcollovati added this pull request to the merge queue Aug 4, 2026

Merged via the queue into main with commit a0e264a Aug 4, 2026
39 checks passed

mcollovati deleted the feat/has-aria-description branch August 4, 2026 07:25

vursen mentioned this pull request Aug 5, 2026

refactor: remove aria-description API from HasAriaDescription #25135

Merged

vursen mentioned this pull request Aug 10, 2026

docs: document ARIA description API for prefix and suffix elements vaadin/docs#5859

Merged

vaadin-bot added the Released with Vaadin 25.3.0-alpha8 label Aug 10, 2026

web-padawan mentioned this pull request Oct 4, 2026

[dialog] Implement HasAriaDescription interface vaadin/flow-components#10336

Closed

Conversation

vursen commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

Uh oh!

github-actions Bot commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results

Uh oh!

vursen Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud Bot commented Aug 4, 2026

Quality Gate passed

Uh oh!

Uh oh!

knoobie commented Aug 4, 2026

Uh oh!

vursen commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vursen commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vursen commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

knoobie commented Aug 5, 2026

Uh oh!

vaadin-bot commented Aug 10, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vursen commented Aug 3, 2026 •

edited

Loading

github-actions Bot commented Aug 3, 2026 •

edited

Loading

vursen Aug 3, 2026 •

edited

Loading

vursen commented Aug 5, 2026 •

edited

Loading

vursen commented Aug 5, 2026 •

edited

Loading

vursen commented Aug 5, 2026 •

edited

Loading