Skip to Main Content
Toggle
(800) 889-9659
info@levelaccess.com

Differences between ARIA 1.0 and 1.1: Changes to role=”combobox”

Bryan Garaventa 01/27/17

This is the fourth and final installment of SSB’s review of the differences between ARIA 1.0 and 1.1. In our last post – Differences between ARIA 1.0 and 1.1: Changes – we reviewed changes to existing attributes such as aria-haspopup, aria-activedescendant, role=”form”, amongst others. Today, we explore the changes to role=”combobox”.

The most recent Candidate Recommendation of the Accessible Rich Internet Applications (WAI-ARIA) specification was published on October 27, 2016. You can view the full document on the W3 website.

It’s important to note that this document is still subject to change with future publications, and that these observations are meant to provide a high level overview of broad level changes that will be important to be aware of going forward. As such these details are likely to remain valid regardless. Also, many of these additions are minimally supported or not supported at all by browsers and assistive technologies as yet.

ARIA role=”combobox”: Introduction

The purpose of role=”combobox” is to enable auto-suggest functionality within editable or readonly edit fields where a list of options can be selected based on conditional rendering.

That sounds ambiguous on purpose, because a Combobox control can be implemented in many different ways, all of which are valid, so it is erroneous to say that a Combobox must be implemented using one specific set of rules. For example, it is valid to have an editable Combobox where a user can type initial values which will auto populate an associated list of options, and it is valid to have a readonly Combobox where a user can set focus to the readonly field and invoke the suggested list of associated options by pressing the Down arrow. It is valid to use native HTML input elements that include type=”text” for this purpose, it is equally valid to use simulated active elements such as focusable HTML div and span elements for this purpose instead, and it is also valid to use this paradigm to reference not only Listbox widgets, but also Grid and Tree widgets, amongst other interactive widget roles.

It is for these reasons that most people still don’t understand how to successfully implement accessible Combobox widgets, because there are so many valid variations that require specific focus management plus specific role usage plus specific scripting behaviors in order for the widget as a whole to function properly for assistive technology users. All of these variations have specific requirements and if they are not met precisely, the widget will work unreliably at best or may instead be totally inaccessible for assistive technology users.

This confusion is now even further exacerbated in ARIA 1.1 because a totally new design pattern has been introduced that has its own set of requirements, which in many ways do not coincide with the ARIA 1.0 design pattern, and yet in other ways these two design patterns overlap. For all of these reasons, it is important to explain the differences clearly and how accessible Combobox widgets should be implemented right now using present day technologies to ensure the highest level of accessibility across platforms and devices, and to forecast the functionality that will be available at some point in the future.

Before getting overly excited about a particular feature or section, read this article through to the end since there are important issues that you must be aware of.

ARIA 1.1 : role=”combobox”

One of the biggest changes is that role=”combobox” in ARIA 1.1 is now a composite widget, meaning that it supports child element roles including active element roles embedded within it. This was not previously true according to the 1.0 mappings where focusable child elements were not supported within role=”combobox”.

Here is the markup syntax for the new ARIA 1.1 Combobox design pattern:

<div aria-label=”Tag” role=”combobox” aria-expanded=”true” aria-owns=”owned_listbox” aria-haspopup=”listbox”>

<input type=”text” aria-autocomplete=”list” aria-controls=”owned_listbox” aria-activedescendant=”selected_option”>

</div>

<ul role=”listbox” id=”owned_listbox”>

<li role=”option”>Zebra</li>

<li role=”option” id=”selected_option”>Zoom</li>

</ul>

 

There are four attributes here that must be dynamically updated, aria-owns and aria-expanded on the container element that includes role=”combobox”, plus aria-controls and aria-activedescendant on the editable HTML input element.

When the associated Listbox is rendered, aria-expanded must be set to “true” and aria-owns plus aria-controls must reference the ID of role=”listbox” . When there is no Listbox rendered, aria-expanded must be set to “false” and aria-owns plus aria-controls should be cleared.

If literal DOM focus remains on the editable HTML input field when the Up/Down arrow keys are used to traverse the rendered Listbox options, then aria-activedescendant must be dynamically updated to reference the ID of the highlighted role=”option” element within the Listbox. The selected role=”option” element should always include aria-selected=”true” and be dynamically updated when this value changes.

It’s important to only set aria-activedescendant after the Down arrow key is used to start traversing the associated Listbox options, and to clear aria-activedescendant by removing the attribute or setting it to “” every time the Left/Right arrow keys are pressed, as with Home/End, Escape, or when typing characters or pasting content into the edit field. Otherwise the accessibility tree will report that focus is within the Listbox and it will be impossible for screen reader users to review the text that has been typed into the edit field.

These attributes must not be mixed up! The attributes aria-haspopup, aria-owns and aria-expanded must only be present on the container element that includes role=”combobox”, and the attributes aria-autocomplete, aria-controls and aria-activedescendant must only be present on the editable HTML input element. Changing where these attributes are located will break this design pattern.

Notice in the above markup that aria-haspopup has been set to “listbox”. This is meant to reflect the correct token value for the associated widget using the new ARIA 1.1 mappings for aria-haspopup.

It is technically possible to set a right-click attached menu on an editable Combobox widget as well, in which case aria-haspopup=”true” or aria-haspopup=”menu” must be added to the HTML input element, and a key event handler must be added so that pressing Shift+F10 or the Applications key (when available) while the editable input field has focus will perform the same action as right-clicking using the mouse in order to render an attached ARIA Menu widget; which also must be programmed correctly.

In the case where a Combobox edit field is readonly, the ‘readonly’ attribute must be added to the HTML input element to prevent typing and to set the readonly state in the accessibility tree.

Another fundamental change to role=”combobox” in ARIA 1.1 is that it now officially supports more complex widget structures such as Grid and Tree. This requires that all such complex structures include proper role assignments and supported attribute usage in the same manner as the previously documented Listbox.

When a Combobox opens an associated Grid, aria-haspopup upon the role=”combobox” container element must be set to “grid” , or if the Combobox opens an associated Tree, then this attribute must be set to “tree” instead.

If literal DOM focus remains on the HTML input element after the associated widget is rendered and while the arrow keys are used to navigate this, then aria-activedescendant must be set to reference the ID of the highlighted role=”gridcell” or role=”treeitem” element in the same manner as described earlier for role=”option” . The associated keyboard paradigm for each of these widget types must be observed as well.

For example, typing any letter or number into the edit field will cause the associated Grid or Tree to be rendered, at which point pressing the Down arrow upon the edit field will set aria-activedescendant to reference the highlighted option within the widget, and the Left/Right/Up/Down/Home/End keys will then control the highlighting within the associated widget while updating the aria-activedescendant attribute accordingly to reflect the currently highlighted role=”gridcell” or role=”treeitem” element. When the associated widget is closed or control is passed back to the focused HTML input element instead, then aria-activedescendant must be removed or set to “” in order to allow for this to be reflected in the accessibility tree, at which point the Left/Up/Right/Home/End keys will be processed normally within the edit field until the Down arrow is used once again to set aria-activedescendant accordingly to reference the highlighted child role within the associated widget.

The role=”combobox” design pattern in ARIA 1.1 also supports the rendering of an associated Dialog widget as well, which requires some special considerations.

  • The attribute aria-haspopup on the role=”combobox” container element must be set to “dialog” to convey the popup type.
  • The attribute aria-activedescendant is not supported for this widget type upon the HTML input element, so focus management is required to handle this interaction. For example, when the Down arrow is pressed while focus is on the HTML input element, the Dialog will be rendered and literal DOM focus must then be moved to a focusable element within the role=”dialog” container element. At which point the user will interact with the Dialog in the same manner as a standard role=”dialog” implementation (if properly constructed). When the Dialog is closed, focus must then be set back to the originating HTML input element within the Combobox.

This illustrates how the new ARIA 1.1 Combobox design pattern is meant to work and how it needs to be constructed for it to do so properly.

Now, and this is really important, don’t do any of this for public usage right now because it will not work reliably or accessibly for assistive technology users! In addition to these new markup requirements not being supported in assistive technologies as yet, they are not supported properly in platform accessibility APIs yet either, making all of these features extremely unreliable and sometimes totally inaccessible at present when implemented.

Until these new features are added with consistent support within accessibility APIs and assistive technologies, the following 1.0 section should be used instead for public usage to build accessible Combobox widgets that work reliably and accessibly across the majority of present-day accessibility APIs and assistive technologies.

ARIA 1.0: “role=combobox”

First, it’s important to understand that the ARIA 1.0 Combobox design pattern is not deprecated, nor will any of the following guidance stop working accessibly in the future. For this reason, the following statement was added to the 1.1 Combobox design pattern to guarantee this.

“The ARIA 1.0 specification describes a combobox pattern where a text input element has the combobox role and owns a listbox element. User agents, assistive technologies, and conformance checkers SHOULD continue to support the ARIA 1.0 pattern so that existing implementations of the ARIA 1.0 pattern remain functional.”

That being said, there are still some important features that are subject to accessibility API changes plus features that the ARIA 1.0 Combobox will inherit automatically that will increase accessibility for this widget type going forward.

Regarding the 1.0 role mappings for Combobox, role=”combobox” was not originally mapped as a composite widget, meaning that the element with role=”combobox” had to be focusable and all supporting attributes had to be present on the same element. No focusable child elements were supported within role=”combobox” .

In the original 1.0 Combobox design pattern, the aria-owns attribute was stated as being required to reference the associated Listbox widget.

However, the most accessible design pattern for the use of role=”combobox” is upon an editable HTML input element. Since the use of aria-owns should not be used on elements that cannot support child elements because this reorders the accessibility tree and causes accessibility issues as a result, aria-owns should not be used with role=”combobox” in this case. Instead, aria-controls should be used in combination with role=”combobox” on the focusable input field to provide the greatest level of accessibility across various browsers and assistive technologies.

With this modification applied, the following markup shows the syntax for the ARIA 1.0 Combobox design pattern:

<input type=”text” aria-label=”Tag” role=”combobox” aria-expanded=”true” aria-autocomplete=”list” aria-controls=”owned_listbox” aria-activedescendant=”selected_option”>

<ul role=”listbox” id=”owned_listbox”>

<li role=”option”>Zebra</li>

<li role=”option” aria-selected=”true” id=”selected_option”>Zoom</li>

</ul>
If you compare this markup with the new 1.1 design pattern syntax, you will see that these two are vastly different. This is the primary reason why the new 1.1 design pattern does not work reliably as yet because all of the accessibility API mappings and screen reader support have been built to process this original 1.0 design pattern instead.

For this 1.0 design pattern, there are three attributes here that must be dynamically updated: aria-expanded, aria-controls, and aria-activedescendant on the focusable HTML input element that includes role=”combobox” .

When the associated Listbox is rendered and navigation is enabled for traversing the role=”option” elements using the arrow keys, aria-expanded must be set to “true” and aria-controls must reference the ID of role=”listbox”. When there is no Listbox rendered or when arrow key navigation between the role=”option” elements is disabled, aria-expanded must be set to “false” and when the Listbox is removed or hidden aria-controls should be cleared.

If literal DOM focus remains on the editable HTML input field when the Up/Down arrow keys are used to traverse the rendered Listbox options, then aria-activedescendant must be dynamically updated to reference the ID of the highlighted role=”option” element within the Listbox. The selected role=”option” element may include aria-selected=”true” , and if present, should be dynamically updated when this value changes.

It’s important to only set aria-activedescendant after the Down arrow key is used to start traversing the associated Listbox options, and to clear aria-activedescendant by removing the attribute or setting it to “” every time the Left/Right arrow keys are pressed, as with Home/End, Escape, or when typing characters or pasting content into the edit field. Otherwise the accessibility tree will report that focus is within the Listbox and it will be impossible for screen reader users to review the text that has been typed into the edit field.

These attributes must not be mixed up! The attributes aria-controls, aria-expanded, aria-autocomplete, and aria-activedescendant must only be present on the editable HTML input element that includes role=”combobox”. Changing where these attributes are located will break this design pattern. This guidance is reflected in the ARIA Role Matrices Combobox section.

In the case where a Combobox edit field is readonly, the ‘readonly’ attribute must be added to the HTML input element with role=”combobox” to prevent typing and aria-readonly=”true” must also be added to the same element to set the readonly state in the accessibility tree.

Now, here is where ARIA 1.1 additions provide enhanced support for the ARIA 1.0 Combobox design pattern.

Since aria-activedescendant is already supported on role=”combobox” , this means it too supports more complex widget structures such as Grid and Tree in addition to Listbox. Moreover, this already works accessibly right now! This requires that all such complex structures include proper role assignments and supported attribute usage in the same manner as the previously documented Listbox.

If literal DOM focus remains on the HTML input element after the associated widget is rendered and while the arrow keys are used to navigate this associated widget, then aria-activedescendant must be set to reference the ID of the highlighted role=”gridcell” or role=”treeitem” element in the same manner as described earlier for role=”option” . The associated keyboard paradigm for each of these widget types must be observed as well.

For example, typing any letter or number into the edit field will cause the associated Grid or Tree to be rendered, at which point pressing the Down arrow upon the edit field will set aria-activedescendant to reference the highlighted option within the widget, and the Left/Right/Up/Down/Home/End keys will then control the highlighting within the associated widget while updating the aria-activedescendant attribute accordingly to reflect the currently highlighted role=”gridcell” or role=”treeitem” element. When the associated widget is closed or control is passed back to the focused HTML input element instead, then aria-activedescendant must be removed or set to “” in order to allow for this to be reflected in the accessibility tree, at which point the Left/Up/Right/Home/End keys will be processed normally within the edit field until the Down arrow is used once again to set aria-activedescendant accordingly to reference the highlighted child role within the associated widget.

To take advantage of the new ARIA 1.1 functionality regarding aria-haspopup, when a Combobox opens an associated Grid, aria-haspopup upon the focusable role=”combobox” element can be set to “grid” , if the Combobox opens an associated Tree, then this attribute can be set to “tree” , or if the Combobox opens an associated Listbox as shown above, then this attribute can be set to “listbox” . This will convey to assistive technology users which type of widget the Combobox is meant to control.

Here too the role=”combobox” design pattern in ARIA 1.0 also inherits support for the rendering of an associated Dialog widget, which requires some special considerations.

  • The attribute aria-haspopup on the role=”combobox” container element should be set to “dialog” to convey the popup type.
  • The attribute aria-activedescendant is not supported for this widget type upon the focusable role=”combobox” input element, so focus management is required to handle this interaction. For example, when the Down arrow is pressed while focus is on the HTML input element, the Dialog will be rendered and literal DOM focus must then be moved to a focusable element within the role=”dialog” container element. At which point the user will interact with the Dialog in the same manner as a standard role=”dialog” implementation (if properly constructed). When the Dialog is closed, focus must then be set back to the originating HTML input element within the Combobox.

This illustrates how the present-day ARIA 1.0 Combobox design pattern works and how it needs to be constructed for it to do so properly.

Lastly, there are some important tweaks that must be done within the scripting to make this work across both desktop and mobile touch screen devices.

When implementing keyboard support, don’t use the onKeyPress handler because onKeyPress is deprecated. Instead, onKeyDown or onKeyUp must be used to process key events.

Typically an editable Combobox input element such as this will generate a list of associated auto-suggest options, which will disappear when the focus moves away from the edit field. This is done using onBlur on the edit field, however this presents critical accessibility issues on touch screen devices. When VoiceOver is running on iOS for example, simply moving one finger around the screen to hear what information the screen contains including what is listed in the associated auto-suggest widget will automatically fire all onFocus and onBlur handlers that are encountered at the same time causing the associated widget to close automatically, thus making it impossible to read the suggested list using VoiceOver.

To solve this, logic must be added to the onBlur script so that the auto-suggest widget will only close automatically when a touch screen device is not being used, otherwise the associated widget will need an additional Close button that can be tapped to close it if desired.

ARIA 1.0 role=”combobox”: Live Examples

The following live pages can be used to test the ARIA 1.0 Combobox design pattern across devices and assistive technologies.

All of these examples are included within the AccDC TSG accessible widget archives, which are reusable modularized components that can be used by inserting them within any web technology, whether powered by jQuery, powered by MooTools, or powered by Dojo, with equal accessibility across each.

ARIA role=”combobox”: Conclusion

Eventually as accessibility API and assistive technology support for the new ARIA 1.1 role=”combobox” design pattern increases and becomes stable, it will provide the same level of reliability and accessibility that is shown in the ARIA 1.0 role=”combobox” design pattern as demonstrated above. Until then however, the 1.0 design pattern is the only one that should be used for public usage because this is the only one that is provably accessible at this time.

It is vitally important that these two design patterns not be confused. Even after the ARIA 1.1 design becomes better supported, web developers must only use either one design pattern or the other, and the associated role and focus movement must be strictly followed in order for this control to function correctly across devices and assistive technologies. Mixing these design patterns in ways that are not described above will result in inaccessible software.

This concludes the ARIA 1.1 versus 1.0 comparison blog post series. Please click here for parts one, two and three. Please share this information far and wide, since it is very important that people implement these widgets accessibly in the future so that they can propagate positively across the web.

Leave a Comment

Your email address will not be published. Required fields are marked *

1 Comments

  1. Thanks so much for putting together this detailed post Bryan. Can you elaborate on your advice regarding using aria-controls over aria-owns for the ARIA 1.0 combobox pattern? Reason I ask: I find that using aria-controls yields a combobox that will not work with Chrome and VoiceOver or Safari and VoiceOver. Perhaps you advice regarding aria-controls is best applied to Windows only?