fix: Combobox VoiceOver announcement not respecting `aria-label` of `ListBoxItem` #8908

SimonSelg · 2025-09-23T14:32:46Z

sIssue describing the problem and the root cause: #8907

This PR fixes the problem I described in detail in the issue linked above. Please note that there is another strategy to fix this, which I outlined in the issue as well.

✅ Pull Request Checklist:

Included link to corresponding React Spectrum GitHub Issue.
Added/updated unit tests and storybook for this change (for new code or code which already has tests).
Filled out test instructions.
Updated documentation (if it already exists for this component).
Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

Refer to the linked issue, which includes detailed reproduction instructions.

Short version:

Open the story called Combo Box List Box Item With Aria Label and activate VoiceOver.
Then interact with the ComboBox and its options via Keyboard
Verify that VoiceOver reads to names specified via aria-label instead of the one specified via textValue.

snowystinger

thanks for catching that and starting a PR!

snowystinger · 2025-09-24T00:38:40Z

packages/@react-aria/collections/src/Document.ts

    node.rendered = rendered;
    node.render = render;
    node.value = value;
+    if (obj['aria-label']) {


generally we try to add as little as possible to these nodes, so I think we'd prefer the other option and read from focusedItem.props['aria-label'] and section.props['aria-label']

Alright. Just to clarify, the attribute aria-label already on the node, it is just not initialized:

react-spectrum/packages/@react-aria/collections/src/BaseCollection.ts

Lines 23 to 42 in 307b71c

export class CollectionNode<T> implements Node<T> {

static readonly type: string;

readonly type: string;

readonly key: Key;

readonly value: T | null = null;

readonly level: number = 0;

readonly hasChildNodes: boolean = false;

readonly rendered: ReactNode = null;

readonly textValue: string = '';

readonly 'aria-label'?: string = undefined;

readonly index: number = 0;

readonly parentKey: Key | null = null;

readonly prevKey: Key | null = null;

readonly nextKey: Key | null = null;

readonly firstChildKey: Key | null = null;

readonly lastChildKey: Key | null = null;

readonly props: any = {};

readonly render?: (node: Node<any>) => ReactElement;

readonly colSpan: number | null = null;

readonly colIndex: number | null = null;

There seems to be a good part of the codebase that is reading aria-label directly from the node, see ListBoxOption.tsx, MenuSection.tsx ...

Would you still prefer the other way (read from focusedItem.props['aria-label'] and section.props['aria-label']) ? In that case I'd suggest to remove the aria-label attribute from the node class altogether and migrate all usages to node.props?.['aria-label'].

Just a small note, I removed the if condition i originally had here to ensure that the sync performed by setProps also works if the react-aria prop changes from a value to undefined.

See https://github.com/adobe/react-spectrum/compare/5a6251896b55a27807bef2630208bfb96a6657df..a11dcf8bb46322cad7d775e3ff27e98b0fc6667f#diff-11dea92f1a0629c980fc22a1e00bf0cebed068aff25abf42c47264618fce3cc6

There seems to be a good part of the codebase that is reading aria-label directly from the node

O, thank you, I'd missed that. Will follow it up with the team and see why we are doing that.

just to update, this was mainly a backcompat addition between the new collections implementation and the old collections implementation which originally added aria-label to the node directly. We'll want to keep aria-label on the node class but reading it from props is fine

thanks for the update and the additional context 👍 appreciate it.

snowystinger · 2025-09-24T00:39:30Z

note, you'll need to sign the CLA https://react-spectrum.adobe.com/contribute.html#contributor-license-agreement

SimonSelg · 2025-09-24T08:53:14Z

I've signed the CLA 👍

SimonSelg · 2025-09-30T07:56:56Z

@snowystinger any updates, do you need anything from me to continue here? happy to hear from you

I rebased on latest main.

This can be used to check whether the screen-reader announcement for option selections reads the correct label for each option, especially on mac, where there is a special codepath for this.

This commit ensures the aria-label prop from the ListItem is read into the corresponding attribute ElementNode

snowystinger · 2025-10-01T01:23:36Z

any updates, do you need anything from me to continue here? happy to hear from you

Not yet, we're in the middle of release testing, so apologies if we move a little slowly.

LFDanLu

Tested locally in VO, verified the announcement came though properly, thanks for fixing this!

SimonSelg · 2025-10-07T08:03:59Z

Thanks for getting this merged and taking the time to make an informed decision about that.

…ListBoxItem` (#8908) * add ComboBox Story for ListBoxItem with aria-label This can be used to check whether the screen-reader announcement for option selections reads the correct label for each option, especially on mac, where there is a special codepath for this. * fix `CollectionBuilder` to handle `aria-label` correctly This commit ensures the aria-label prop from the ListItem is read into the corresponding attribute ElementNode * only add key if it exists --------- Co-authored-by: Robert Snow <rsnow@adobe.com> Co-authored-by: Robert Snow <snowystinger@gmail.com>

SimonSelg mentioned this pull request Sep 23, 2025

Combobox VoiceOver announcement not respecting aria-label of ListBoxItem #8907

Closed

snowystinger reviewed Sep 24, 2025

View reviewed changes

SimonSelg force-pushed the fix-combobox-item-aria-label branch from 5a62518 to a11dcf8 Compare September 24, 2025 09:40

SimonSelg added 2 commits September 30, 2025 09:59

add ComboBox Story for ListBoxItem with aria-label

189e8a6

This can be used to check whether the screen-reader announcement for option selections reads the correct label for each option, especially on mac, where there is a special codepath for this.

fix CollectionBuilder to handle aria-label correctly

7e694f6

This commit ensures the aria-label prop from the ListItem is read into the corresponding attribute ElementNode

SimonSelg force-pushed the fix-combobox-item-aria-label branch from a11dcf8 to 7e694f6 Compare September 30, 2025 08:04

snowystinger added the ready for review label Oct 1, 2025

LFDanLu changed the title ~~Fix Combobox VoiceOver announcement not respecting aria-label of ListBoxItem~~ fix: Combobox VoiceOver announcement not respecting aria-label of ListBoxItem Oct 6, 2025

LFDanLu previously approved these changes Oct 6, 2025

View reviewed changes

snowystinger and others added 2 commits October 7, 2025 06:35

Merge branch 'main' into fix-combobox-item-aria-label

5cb7760

only add key if it exists

002423a

snowystinger dismissed LFDanLu’s stale review via 002423a October 6, 2025 19:40

snowystinger approved these changes Oct 6, 2025

View reviewed changes

LFDanLu approved these changes Oct 6, 2025

View reviewed changes

LFDanLu added this pull request to the merge queue Oct 6, 2025

Merged via the queue into adobe:main with commit 9bf119b Oct 6, 2025
31 checks passed

	export class CollectionNode<T> implements Node<T> {
	static readonly type: string;
	readonly type: string;
	readonly key: Key;
	readonly value: T \| null = null;
	readonly level: number = 0;
	readonly hasChildNodes: boolean = false;
	readonly rendered: ReactNode = null;
	readonly textValue: string = '';
	readonly 'aria-label'?: string = undefined;
	readonly index: number = 0;
	readonly parentKey: Key \| null = null;
	readonly prevKey: Key \| null = null;
	readonly nextKey: Key \| null = null;
	readonly firstChildKey: Key \| null = null;
	readonly lastChildKey: Key \| null = null;
	readonly props: any = {};
	readonly render?: (node: Node<any>) => ReactElement;
	readonly colSpan: number \| null = null;
	readonly colIndex: number \| null = null;

fix: Combobox VoiceOver announcement not respecting aria-label of ListBoxItem #8908

fix: Combobox VoiceOver announcement not respecting aria-label of ListBoxItem #8908

Conversation

SimonSelg commented Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull Request Checklist:

📝 Test Instructions:

Uh oh!

snowystinger left a comment

Choose a reason for hiding this comment

Uh oh!

snowystinger Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

SimonSelg Sep 24, 2025 • 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!

SimonSelg Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

snowystinger Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

LFDanLu Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

SimonSelg Oct 7, 2025

Choose a reason for hiding this comment

Uh oh!

snowystinger commented Sep 24, 2025

Uh oh!

SimonSelg commented Sep 24, 2025

Uh oh!

SimonSelg commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

snowystinger commented Oct 1, 2025

Uh oh!

LFDanLu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

SimonSelg commented Oct 7, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fix: Combobox VoiceOver announcement not respecting `aria-label` of `ListBoxItem` #8908

fix: Combobox VoiceOver announcement not respecting `aria-label` of `ListBoxItem` #8908

SimonSelg commented Sep 23, 2025 •

edited

Loading

SimonSelg Sep 24, 2025 •

edited

Loading

SimonSelg commented Sep 30, 2025 •

edited

Loading