A possible ARIA solution to improve accessibility of the WordPress Add Media Panel

Published: | 2 Comments

Reading Time: 5 minutesThe Add Media panel was introduced in WordPress version 3.5 at the end of 2012. It’s aim was to to improve the user experience of adding media (usually images, but also documents) into pages and posts.

WordPress Add Media panel

WordPress Add Media panel

For sighted users and those who can use a mouse it may be a better experience than the previous method. But unfortunately the design and functionality mean it is impossible to use for anyone who relies on keyboard interaction. Of course this includes anyone who is using a screen reader.

Users of voice recognition software such as Dragon Naturally Speaking also have a hard time interacting with the modal window.

This post discusses the the problem of selecting media files within the Add Media panel and looks at a couple of ways to solve this – one demonstrating how using ARIA can help overcome accessibility issues.

The nature of the problems

The main showstopper accessibility issue with the Add Media Panel is keyboard interaction.

The panel can be opened successfully using keystrokes and the links at the top of the panel can be accessed. But beyond that it is impossible to tab to the individual media thumbnails, and thus to select them to update details and insert them into the page or post.

This is not the only accessibility issue with the Add Media Panel, but the one I want to address in this post.

So why can’t you tab to the items?

In order to see why tabbing to the media items is not possible we need to look at the underlying HTML code from the media list in the Add Media panel. Here is an example image from my own site:

<li class="attachment save-ready">
<div class="attachment-preview type-image subtype-jpeg landscape">
<div class="thumbnail">
<div class="centered">
<img src="http://www.coolfields.co.uk/wp-content/uploads/pen-pad02-300x225.jpg" draggable="false">
<a class="check" href="#" title="Deselect"><div class="media-modal-icon"></div></a>

The first thing you’ll notice about this is that there are no elements that can get keyboard focus apart from the link that has the title ‘Deselect’. This code snippet is taken from an initial view with no media files selected, and this link has a CSS property of display:none so it will not feature in the tab order and will also be ignored by screen readers etc.

The second thing to note is that even if something could get focus, there is nothing to identify the media file in a textual way – either by plain text or by alternate text on the media file thumbnail. So screen readers will voice nothing for it, and voice recognition users have no direct handle to access the item.

During the 3.6 development window I raised three trac tickets to cover the accessibility issues found when using the Add Media panel with keyboard operation, with screen readers and with voice recognition software.

Progressive enhancement points to the ideal solution

The action required to add a media file to a page or post¬†is firstly, to select one of the thumbnails, and then secondly, use the ‘Insert into post’ button to add the file. It is possible within this panel to select more than one media file at a time and add them all in one go.

If you think about it, this action is exactly the same as using a checkbox grouping – selecting one or more items and then actioning a button. And that would be the best way to solve the accessibility issues here. The underlying code should be something like:

<li class="attachment save-ready">
<input type="checkbox" name="media123" id="media123" value="">
<label for="media123"><img src="http://www.coolfields.co.uk/wp-content/uploads/pen-pad02-300x225.jpg" alt="Alt text for image"></label>

With progressive enhancement principles, a javascript layer could then be applied on top to get the visual appearance to be something like what was introduced in WordPress 3.5 – but keeping the underlying semantic solution intact for users of assistive technology.

Unfortunately implementing this ideal solution would require some significant redevelopment of the Add Media functionality – one of the common costs of not getting accessibility right in the first place.

A pragmatic solution using ARIA

There was no activity on the three trac tickets for some time. So towards the end of the 3.6 development cycle it became obvious that in order to get any accessibility improvement to the Add Media panel a quick pragmatic solution would be needed.

Having done some investigation on a number of ARIA attributes I proposed a solution that would involve only minor changes to the existing code, but would in theory improve the accessibility for some people. With the help of core WordPress developer Dave Martin (@lessbloat) a patch was prepared and tested. We decided to target the list item element for each media file using this solution:

<li class="attachment save-ready" tabindex="0" role="checkbox" aria-checked="false" aria-label="Media file title">

So how does it work?

What we’re trying to do here is to effectively pretend to assistive technology that the list item is actually a checkbox. There’s quite a lot going on there with the addition of the four attributes. Let’s consider each one in turn.


This is not strictly-speaking an ARIA attribute, but addresses the keyboard focus issue. Using tabindex=”0″ tells browsers to include an element within the tab order of a page – even if the element wouldn’t normally be able to receive focus. The element’s order within the tabbing list is determined by its position within the HTML stream.


Selected and unselected images

Selected and unselected images

This ARIA attribute tells screen readers that this element is to be treated as if it is behaving as a checkbox. In situations where only one media file can be selected (eg. allocating a featured image) a role="radio" attribute would be more appropriate.


This attribute should always accompany the role="checkbox" attribute and indicates to screen readers whether the element acting as a checkbox (or radio button) is selected or not. When selected, the attribute value should change to aria-checked="true".

aria-label=”Media file title”

When using ‘real’ form elements, each input should have an accompanying label element to describe to the user what input is required. It is not valid HTML to attach a label to elements other than input elements so the aria-label attribute can contain the prompt for the input – and this can be accessed by screen readers. In this case the attribute will pick up whatever the user has allocated as a title when the media file was uploaded. If no title was allocated then this would default to the original file name minus the file type suffix.

Alongside the ARIA attributes, some changes needed to be made to the javascript that drives the Add Media screen:

  • To toggle the aria-checked state as media items are selected/deselected.
  • To allow the space bar to be used to select and deselect the media files.

The downside of using ARIA

These ARIA techniques are well documented, but they are still relatively new. Older browsers and older versions of assistive technology like screen readers may not recognise them or behave in unpredictable ways.

That said, this solution was successfully tested using the latest version of NVDA screen reader in conjunction with a recent version of the Firefox browser. An up-to-date version of JAWS alongside IE9 also worked as expected.

Currently, Dragon Naturally Speaking (popular voice recognition software) does not recognise these ARIA attributes so the only way for Dragon users to interact with the Add Media panel is via mouse emulation. It’s not ideal but it is possible.

So that’s sorted then, isn’t it?

Unfortunately not. Despite having been tested successfully and obviously improving the experience for keyboard only users and users of newer screen readers, the fix was pulled from WordPress 3.6 before its release.

At this stage it is not clear when this solution will be applied.

A new series of trac tickets (#25100, #25101, #25102, #25103, #25105, #25111) have been created to address some of the other accessibility issues with Add Media, but as at September 2013 there is no movement on the main issue.

Any comments or suggestions?

If you’ve got some views on this issue or on this post please get in touch. You can use the comment form below.

Other Accessibility posts

Share this page (Links open new windows/tabs)

  • Share this page on LinkedIn (opens new window)
  • Share this page on Delicious (opens new window)
  • Share this page on Digg (opens new window)
  • Share this page on Posterous (opens new window)
  • Share this page on Reddit (opens new window)

2 Responses to “A possible ARIA solution to improve accessibility of the WordPress Add Media Panel”

  1. From: Amanda on November 24th, 2013 at 11:16 am

    I really should go leave some comments on those tickets. I, for one, would love it if the solution you came up with gets implemented, and soon.

  2. From: Graham Armfield on November 24th, 2013 at 7:46 pm

    Some good news is that the patch has been resurrected at Wordcamp London and has been tested with JAWS and NVDA. Also, the situation is good for those who rely on keyboard interaction alone.

    I’m hoping that this solution will be in WordPress 3.8.

Like to leave a comment?

Please note: All comments are moderated before they will appear on this site.

Previous post:

Next post: