Monday, November 17, 2014

Using ngAria

A new feature released in Angular 1.3.0 is the accessibility module, ngAria. As someone involved in delivering this community-driven effort, I thought it might be helpful to introduce ngAria, a module which can improve the user experience for many people with disabilities.

In this post:

What is ngAria?

The goal of ngAria is to improve the default accessibility of Angular.js by enabling common ARIA attributes for directives. Using ngAria is as simple as requiring the ngAria module in your application. It then hooks silently into standard Angular.js directives and injects accessibility support into your application at runtime.

Currently, ngAria interfaces with the following directives: ngModel, ngShow, ngHide, ngDisabled, ngClick, ngDblclick and ngMessages. The list of supported attributes is currently limited; we are identifying additional ways the module can improve accessibility, described later on in this post.

Related reading: What is WAI-ARIA, what does it do for me, and what not?

By centralizing accessibility features into one module, they can be easily added and tested, allowing ngAria to grow over time. On the flip-side, automatic accessibility features are only added if the module is included, making it possible for accessibility to be forgotten—something we can’t continue to do as developers. When you include ngAria in your projects, you can improve the experience for many of your users without doing much at all. However, it’s important to inform yourself about ngAria’s capabilities and limitations so you know what it actually does to your code.

To learn how ngAria works with the directives listed above, explore the ngAria Developer Guide.

Why ngAria?

Many people in the world depend on assistive technologies such as screen readers, high contrast mode, braille keyboard support, closed captioning and more to use the web applications and services we take for granted. The popularity of MV* frameworks such as Angular.js has contributed many inaccessible web applications as our attention has gone to shinier topics such as mobile performance, databinding, automated tooling and ES6 support. We love to innovate the way we work, yet we forget basic things such as HTML semantics and supporting the keyboard.

In the past, Angular.js didn’t do much for accessibility–in fact, it made it more challenging by injecting attributes that didn’t work for accessibility, such as disabled on a custom element directive like <md-checkbox>.

See this rendered markup example:

<md-checkbox ng-model="someModel" ng-disabled="isDisabled" disabled>
    Inaccessible Checkbox

The above checkbox directive is inaccessible because it doesn't communicate anything to assistive technologies and it's inoperable from the keyboard. Although it's easy to use directives like ng-disabled on non-semantic elements, this leaves us responsible to also manage ARIA by ourselves. A helpful framework would eliminate this kind of pain and do the heavy lifting where we needed it.

With the introduction of ngAria, common ARIA attributes are now handled by default when the module is included, helping to communicate the state of our application to users of assistive technologies.

Let's look at the same markup after ngAria has done its magic:

<md-checkbox ng-model="someModel" aria-disabled="true" tabindex="0">

Note: this example also requires role="checkbox" and aria-label to be accessible. In Angular Material, we handle this internally but those attributes could become managed by ngAria in the future.

Including ngAria

Using ngAria is as simple as requiring the ngAria module in your application:

angular.module('myApp', ['ngAria'])...

After including the module, any directives in your code that ngAria is hooked into will be automatically fitted with ARIA attributes. To learn more about ngAria's effect on directives, check out the ngAria Developer Guide.

Disabling attributes

Because ngAria's attribute magic may not work for every scenario, you can opt out of specific ARIA attributes by configuring ngAria with $ariaProvider:

angular.module('myApp', ['ngAria'], function config($ariaProvider) {
    tabindex: false

For the full list of configurable properties, visit the API Documentation for $ariaProvider.

New to ngAria


A recent pull request for ngAria and ngMessages, the module for form validations, will improve accessibility by also reading errors aloud in a screen reader as they become visible. This functionality can be enabled by adding aria-live to the ng-messages directive. It's a simple way to expose dynamic content to assistive technologies and is a good example of the type of problem ngAria should help to solve.

Proposed for ngAria or Elsewhere

ARIA Role Handling

To communicate better to assistive technologies, ngAria should add missing roles to non-semantic elements such as <md-checkbox> and <div type="range">. An issue has been filed to track these two small features and more will be added as they come up.

End-to-End Accessibility Testing with Protractor

Early work has begun on a plugin system for Protractor that would allow automated integration testing for accessibility as well as ng-hint. Rough ideas for automated testing include HTML hierarchy audits, keyboard operability tests, logs for missing labels and color contrast warnings. Catching accessibility issues before they are deployed gives you more time to fix them and is a lot more fun. Stay tuned for updates as we have them!


An ARIA service method in Angular Material aims to improve a common accessibility issue: forgotten labels, which add accessible names to elements for assistive technologies. For commonly mislabeled components, such as checkboxes or radio buttons, $mdAria will attempt to copy text content to the aria-label attribute. If no suitable text is found, a warning will be logged to the JavaScript console telling the developer they forgot a label for accessibility. We are fixing bugs with this utility as they come up and evaluating whether it could be useful in ngAria or ngHint.

Other Ideas

Some other things we have discussed or proposed for Angular accessibility: warnings for missing alt attributes, default keyboard bindings such as the escape key or question mark key, color contrast assessments and more. I'm excited to see this list grow as we dogfood ngAria on Angular Material and see it battle-tested in the community. If there are things you feel ngAria should do, please write about it in the comments or submit a pull request.

Let's Make it Better

It is our responsibility as developers to build accessible, well-tested web applications. However, the frameworks we use should do as much as possible to improve accessibility by default. As a new module, ngAria will continue to evolve as we discover common use cases it can handle or warn about. Balancing performance and developer experience with end-users' needs requires careful planning and execution, which means it will take time to get right. Consider contributing on Github if you have ideas for ngAria and feel free to comment!

Special Thanks

The module was originally contributed by @arbus, with feedback and improvements from the community through Github issues, pull requests and support from members of the Angular.js core team: Tobias Bosch, Brian Ford, Marcy Sutton and Pete Bacon Darwin.

No comments:

Post a Comment

Note: Only a member of this blog may post a comment.