MenuItem and QueryList ScreenReader Accessibility Improvements #7543

caitlinmcdougall · 2025-08-13T08:47:53Z

Fixes #0000

Checklist

Includes tests
Update documentation

Changes proposed in this pull request:

ScreenReader accessibility improvements for the ItemRenderer, MenuItem, QueryList and Select components

Added proper ARIA relationships and controls:

Added id prop to ItemRenderer interface to enable aria-activedescendant pattern
Enhanced MenuItem component to accept and use the id prop
Added aria-controls pointing to the listbox in select component
Proper aria-activedescendant that references the currently focused option

Improved focus management in QueryList:

Added listboxHasVisualFocus state to track when arrow key navigation is active
Only set aria-activedescendant when users navigate with arrow keys, not during typing
Added handleInputFocus and handleInputBlur methods to manage this behavior
Clear visual focus state when input receives focus or user starts typing

Updated films example:

Modified getFilmItemProps return type to use Omit<MenuItemProps, "key"> to prevent React key conflicts
Added conditional id prop spreading in the props object

Reviewers should focus on:

Ensuring this allows for backwards compatibility with other users of the component.

Screenshot

changelog-app · 2025-08-13T08:47:59Z

Generate changelog in `packages/select/changelog/@unreleased`

Type (Select exactly one)

Feature (Adding new functionality)
Improvement (Improving existing functionality)
Fix (Fixing an issue with existing functionality)
Break (Creating a new major version by breaking public APIs)
Deprecation (Removing functionality in a non-breaking way)
Migration (Automatically moving data/functionality to a new system)

Description

MenuItem and QueryList ScreenReader Accessibility Improvements

Check the box to generate changelog(s)

Generate changelog entry

svc-palantir-github · 2025-08-13T09:43:40Z

Remove redundant optionality

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

svc-palantir-github · 2025-08-13T10:21:59Z

Merge branch 'develop' into cmcdougall/accessibility_changes_menu_item

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

ggdouglas

I'm a bit confused as to what the specific accessibility improvements here are. Can you provide some examples of what you're trying to achieve?

Generally supportive of allowing id to be passed on to MenuItem and for setting aria-activedescendant (though I have questions regarding how this is currently implemented).

ggdouglas · 2025-08-13T14:23:58Z

packages/select/src/__examples__/films.tsx

-    { handleClick, handleFocus, modifiers, query, ref }: ItemRendererProps,
-): MenuItemProps & React.Attributes {
+    itemProps: ItemRendererProps,
+): Omit<MenuItemProps, "key"> & React.Attributes {


If we're omitting key from MenuItemProps for the return type, we should also remove React.Attributes since the intersection of that type just ends up adding it back:

interface Attributes { key?: Key | null | undefined; }

Suggested change

): Omit<MenuItemProps, "key"> & React.Attributes {

): Omit<MenuItemProps, "key"> {

I'm supportive of this fix for the docs examples, but could we split that part out into its own PR?

That makes sense, thank you. I mostly am keeping in the docs examples as it is useful for my testing. Unless I'm not supposed to test on the docs examples? What is the better way to test?

ggdouglas · 2025-08-13T14:27:15Z

packages/select/src/components/query-list/queryList.tsx

 * limitations under the License.
 */

+import * as React from "react";


This React import can be removed:

Suggested change

import * as React from "react";

Will remove thank you

ggdouglas · 2025-08-13T14:40:28Z

packages/select/src/components/query-list/queryList.tsx

        super(props);

+        // Generate unique ID for accessibility
+        this.listId = props.listId ?? `bp5-query-list-${Utils.uniqueId("ql")}`;


Suggest removing the hardcoded version prefix and replacing with the following:

Suggested change

this.listId = props.listId ?? `bp5-query-list-${Utils.uniqueId("ql")}`;

this.listId = props.listId ?? Utils.uniqueId("bp-query-list");

ggdouglas · 2025-08-13T14:41:52Z

packages/select/src/components/query-list/queryList.tsx

+        // When input gains focus, we don't immediately set visual focus state
+        // Visual focus state is only set when the user navigates with arrow keys
+        // This ensures screen readers only announce activedescendant when appropriate
+    };


Why are we defining this empty focus event handler?

Missed this, will remove thank you!

ggdouglas · 2025-08-13T15:03:35Z

packages/select/src/components/query-list/queryList.tsx

+                menuProps: {
+                    ...menuProps,
+                    id: this.listId,
+                    role: "listbox",


The default itemListRenderer implementation already includes this role. Do we need to include it again here?

blueprint/packages/select/src/components/query-list/queryList.tsx

Line 367 in 3029aa2

<Menu role="listbox" {...listProps.menuProps} ulRef={listProps.itemsParentRef}>

Will remove thank you

ggdouglas · 2025-08-13T16:07:04Z

packages/select/src/components/query-list/queryList.tsx

-                menuProps,
+                menuProps: {
+                    ...menuProps,
+                    id: this.listId,


Won't setting an id here replace the id referenced by the outermost combobox that already defines aria-controls? I'm a bit confused as to what we're trying to accomplish. Here's a before/after of these changes on a simple example to illustrate:

Before After

https://codesandbox.io/p/sandbox/v4x4r8

ggdouglas · 2025-08-13T16:21:04Z

packages/select/src/components/select/select.tsx


        const input = (
            <InputGroup
+                aria-activedescendant={listProps.activeItemId}


Why are we setting aria-activedescendant on the filter input group? Shouldn't we be setting this on the outermost combobox element?

Here's the WAI Select-Only Combobox Example for reference:

The aria-activedescendant is on the InputGroup because that's the element that has keyboard focus when users navigate the options with arrow keys. The outermost combobox element loses focus once the popover opens and the InputGroup is focused. Happy to revise if this doesn't make sense.

I have moved the other aria details to the InputGroup now to be consistent

svc-palantir-github · 2025-10-30T19:35:42Z

Address PR feedback

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

svc-palantir-github · 2025-10-30T19:49:04Z

Remove redundant handleInputFocus

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

svc-palantir-github · 2025-10-30T20:37:59Z

Fix voiceOver getting confused when text rerenders

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

Use active descendant and visual focus to announce the current option

32bc79b

Remove redundant optionality

9b3e656

Merge branch 'develop' into cmcdougall/accessibility_changes_menu_item

a780725

caitlinmcdougall marked this pull request as draft August 13, 2025 10:11

ggdouglas reviewed Aug 13, 2025

View reviewed changes

Address PR feedback

9bb1933

Remove redundant handleInputFocus

5cb5939

Fix voiceOver getting confused when text rerenders

7dcc8f7

	): Omit<MenuItemProps, "key"> & React.Attributes {
	): Omit<MenuItemProps, "key"> {

	this.listId = props.listId ?? `bp5-query-list-${Utils.uniqueId("ql")}`;
	this.listId = props.listId ?? Utils.uniqueId("bp-query-list");

MenuItem and QueryList ScreenReader Accessibility Improvements #7543

Are you sure you want to change the base?

MenuItem and QueryList ScreenReader Accessibility Improvements #7543

Conversation

caitlinmcdougall commented Aug 13, 2025

Fixes #0000

Checklist

Changes proposed in this pull request:

Reviewers should focus on:

Screenshot

Uh oh!

changelog-app bot commented Aug 13, 2025

Generate changelog in packages/select/changelog/@unreleased

Uh oh!

svc-palantir-github commented Aug 13, 2025

Remove redundant optionality

Uh oh!

svc-palantir-github commented Aug 13, 2025

Merge branch 'develop' into cmcdougall/accessibility_changes_menu_item

Uh oh!

ggdouglas left a comment

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!

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!

svc-palantir-github commented Oct 30, 2025

Address PR feedback

Uh oh!

svc-palantir-github commented Oct 30, 2025

Remove redundant handleInputFocus

Uh oh!

svc-palantir-github commented Oct 30, 2025

Fix voiceOver getting confused when text rerenders

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Generate changelog in `packages/select/changelog/@unreleased`