Make WordPress Core

Opened 5 years ago

Closed 4 years ago

Last modified 4 years ago

#47146 closed defect (bug) (fixed)

Live search does not announce results to assistive technologies

Reported by: anevins's profile anevins Owned by: afercia's profile afercia
Milestone: 5.3 Priority: normal
Severity: normal Version:
Component: Media Keywords: has-screenshots wpcampus-report has-patch
Focuses: accessibility, javascript Cc:


Moved from the WPCampus accessibility report issues on GitHub, see

  • Severity:
    • Medium
  • Affected Populations:
    • Blind
    • Low-Vision
    • Cognitively Impaired
  • Platform(s):
    • Windows - Screen Reader
    • Mac - VoiceOver
    • Android - TalkBack
    • iOS - VoiceOver
  • Components affected:
    • Media Dialog

Issue description
When users in the "Featured Image" modal's "Media Library" do a
search using the search/filter control, the results change dynamically,
however these changes are not announced to screen readers, so blind and
low-vision users cannot tell what, if anything, matches the search
without manually reading through the image list.

Assistive technologies rely on state information to understand the
behaviour of dynamic content, and if this information is incomplete or
inaccurate it may create a confusing experience for users.

Issue Code

    <div class="media-toolbar-primary search-form">

        <label for="media-search-input" class="screen-reader-text">Search Media</label>

        <input type="search" placeholder="Search media items..." id="media-search-input" class="search">


Remediation Guidance
Use a live region to announce the number of matched results, updating as
users type and delete characters (ideally with a short timeout or
throttling so that the announcements don't interfere with user typing).

Relevant standards

Note: This issue may be a duplicate with other existing accessibility-related bugs in this project. This issue comes from the Gutenberg accessibility audit, performed by Tenon and funded by WP Campus. This issue is GUT-63 in Tenon's report

Attachments (9)

57186783-46999500-6e9a-11e9-8473-8f8d18e486b2.png (365.2 KB) - added by anevins 5 years ago.
47146.diff (4.7 KB) - added by afercia 4 years ago.
47146.2.diff (4.3 KB) - added by afercia 4 years ago.
double spoken message Firefox NVDA.png (147.7 KB) - added by afercia 4 years ago.
47146.3.diff (5.1 KB) - added by afercia 4 years ago.
47146-test.diff (6.6 KB) - added by afercia 4 years ago.
47146.4.diff (6.4 KB) - added by afercia 4 years ago.
aria modal true and live regions.jpg (200.1 KB) - added by afercia 4 years ago.
Live region ignored because of aria-modal="true" (Safari)
47146.5.diff (6.4 KB) - added by afercia 4 years ago.

Download all attachments as: .zip

Change History (25)

#1 @afercia
5 years ago

  • Milestone changed from Awaiting Review to 5.3

This ticket was mentioned in Slack in #core-media by antpb. View the logs.

4 years ago

#3 @antpb
4 years ago

This issue was discussed in the recent Media meeting and one approach shared by @joemcgill is utilizing wp.a11y.speak() to update users on the changes. We should get a a11y experts opinion on that, but this is one approach. Anyone have any suggestions?

Link to speak docs:

#4 @afercia
4 years ago

@antpb thanks for looking into this.

Implementation would be pretty simple, you can have a look at the Themes search or the Plugins search. Worth noting:

  • the speak message needs to be debounced while users are typing (sams of themes/plugins search)
  • this needs to be implemented also in the Media Library grid (and wherever there's a search)

4 years ago

#5 @afercia
4 years ago

  • Focuses javascript added
  • Keywords has-patch added; needs-patch removed
  • Owner set to afercia
  • Status changed from new to assigned

47146.diff is a proof of concept. It implements a spoken message to announce the search results via wp.a11y.speak() both in the Media modal and in the Media Library.

I'd greatly appreciate feedback from the media team and backbone.js models experts :) WordCamp Europe 2019 contributor day is in two days and it would be a great opportunity to work together on this.

4 years ago

#6 @afercia
4 years ago

In 47146.2.diff:

During WCEU Berlin contributor day I had the pleasure to collaborate with @aduth and @loreleiaurora. Looking into the media backbone.js models and the way attachments are fetched / cached, the approach in this patch seemed good enough.

For non-cached queries, there's a minor issue: the spoken message is triggered twice. This appears to happen because of the specific implementation to retrieve attachments in the models. Even after a good amount of time was spent trying to fully understand this part of (mostly undocumented) code, we haven't been able to avoid the double triggering. It doesn't affect the way screen readers announce the speak() message though.

Any improvement and feedback are welcome.

#7 @afercia
4 years ago

It doesn't affect the way screen readers announce the speak() message though.

Correction: while it doesn't affect Safari + VoiceOver, it does affect screen readers on Windows. See the double spoken message in the attached screenshot, testing with Firefox and NVDA. This issue needs to be solved, as the double announcement would be very confusing for screen readers users.

4 years ago

#8 @afercia
4 years ago

47146.3.diff builds on top of the previous patch and does a few things:

  • Uses underscore.js debounce() to avoid the multiple announcements: 200ms is a "magic number" and I'd like there was a better method to avoid debounce entirely. For now, it works.
  • Handles the case when the search results have "more" results that get displayed when scrolling the page. This actually depends on the viewport and happens when there are many search results. Also, worth considering #40330 proposes to remove the infinite scrolling.
  • the console.log()s are for testing purposes

Worth noting that cropped images are not displayed in the media grid, while the list view does displays them. This may produce a mismatch between the "per page" parameter, which defaults to 40, and the actual number of results: when a cropped image is in the set of 40 results, only 39 attachments are actually displayed in the grid. I believe there's already a specific ticket about this issue.

Some testing and suggestions to avoid debounce() would be nice :)

This ticket was mentioned in Slack in #core-media by anevins. View the logs.

4 years ago

#10 @anevins
4 years ago

Hey @afercia , just checking you're okay owning this for 5.3? If not, no pressure, we can get this reassigned.

#11 @afercia
4 years ago

Hey @anevins thanks for the ping. I can own it and also assign to someone else for review, no strong preferences.

The patch needs review from backbone.js experts. We looked at it during WCEU contributor day with @aduth and @loreleiaurora. Couldn't find a better way to determine when a search is "complete" and results are fully received. /Cc @adamsilverstein

4 years ago

4 years ago

#12 @afercia
4 years ago

  • Keywords commit added

Testing again the proposed patch, turns out the aria-modal="true" added to the media dialog in [45572] / #47145 prevents the ARIA live regions to work as expected. For example with Safari + VoiceOver, the live regions are ignored and the speak() messages are not announced. See the attached screenshot.

This is the intended behavior of aria-modal="true" which is meant to hide from assistive technologies any content that lives outside the element it is applied to.

Given the current implementation of the speak() ARIA live region, aria-modal="true" can't be used. I removed it from the latest patches.

47146-test.diff is for testing purposes: it logs to the console the spoken messages.

47146.4.diff looks good for commit to me.

Test with a good browser / screen reader combination e.g.:

  • Safari + VoiceOver
  • Firefox + NVDA
  • Chrome + JAWS


  • search for attachments in the media modal dialog or in the media library
  • check search results are announced
  • in the media modal: when the search returns more than 40 results (40 is the default limit) for example searching for jpg assuming you have more than 40 jpg images:
    • the first message is Number of media items displayed: 40. Scroll the page for more results. (*note 1)
    • scroll the page and a second message announces the new number of results

Note 1: as mentioned previously, cropped images produce a mismatch between the "per page" parameter and the actual number of results. For example when there are 2 cropped images, the message will be:
Number of media items displayed: 40 ...

This should be addressed separately.

4 years ago

Live region ignored because of aria-modal="true" (Safari)

This ticket was mentioned in Slack in #accessibility by audrasjb. View the logs.

4 years ago

4 years ago

#14 @afercia
4 years ago

47146.5.diff refreshes the patch (because of line number changes).

#15 @afercia
4 years ago

  • Resolution set to fixed
  • Status changed from assigned to closed

In 46239:

Accessibility: Media: Make screen readers announce the Media search results.

  • adds audible messages via wp.a11y.speak() to announce the search results
  • removes a keyup event that was there only to support old browsers
  • removes aria-modal="true" from the media modal dialog as it prevents the ARIA live regions to be perceived by screen readers
  • triggers the search only after 2 ASCII characters have been typed

Props anevins, antpb, aduth, loreleiaurora, afercia.
Fixes #47146.

#16 @afercia
4 years ago

  • Keywords commit removed
Note: See TracTickets for help on using tickets.