universal-design-center

ARIA Best Practices

Source: W3C recommendations - Web Accessibility Initiative - aria

  Accessible Rich Internet Applications (WAI-ARIA) 1.1 

Accessibility of web content requires semantic information about widgets, structures, and behaviors, in order to allow assistive technologies to convey appropriate information to persons with disabilities. This specification provides an ontology of roles, states, and properties that define accessible user interface elements and can be used to improve the accessibility and interoperability of web content and applications.

  No ARIA is better than bad ARIA

If standard semantics in HTML markup is used, it is not necessary to use ARIA and you should only use HTML. Functionally, ARIA roles, states, and properties are similar to a CSS for assistive technologies. For screen reader users, ARIA controls the rendering of their non-visual experience. Incorrect ARIA misrepresents visual experiences, with potentially devastating effects on their corresponding non-visual experiences.

  Understanding Essential Principles 

ARIA Role

Is a promise to incorporate JavaScript that provides the interaction expected from a given role. For example, a <div> with a role "button" is expected to act as a button and provide keyboard interaction behavior, which requires JavaScript to fulfill this promise. 

ARIA States and Properties

Are attributes that add information about the behavior of an HTML element. States and Properties are mapped to accessibility frameworks (such as a screen reader) that use this information to provide alternative access solutions. 

For example:

  • The button has role of button.
  • The button has an accessible label. By default, the accessible name is computed from any text content inside the button element. However, it can also be provided with aria-labelledby or aria-label.
  • If a description of the button's function is present, the button element has aria-describedby set to the ID of the element containing the description.
  • When the action associated with a button is unavailable, the button has aria-disabled set to true.
  • If the button is a toggle button, it has an aria-pressed state. When the button is toggled on, the value of this state is true, and when toggled off, the state is false.

  ARIA best practices for different widgets  

Aria roles, states and properties are described in each of the following common widgets, to properly incorporate semantic structure and interaction behavior for each widget.

Accordion

Roles, States, and Properties 

  1. The title of each accordion header is contained in an element with role button.
  2. Each accordion header button is wrapped in an element with role heading that has a value set for aria-level that is appropriate for the information architecture of the page.
  3. If the native host language has an element with an implicit heading and aria-level, such as an HTML heading tag, a native host language element may be used.
  4. The button element is the only element inside the heading element. That is, if there are other visually persistent elements, they are not included inside the heading element.
  5. If the accordion panel associated with an accordion header is visible, the header button element has aria-expanded set to true. If the panel is not visible, aria-expanded is set to false.
  6. The accordion header button element has aria-controls set to the ID of the element containing the accordion panel content.
  7. If the accordion panel associated with an accordion header is visible, and if the accordion does not permit the panel to be collapsed, the header button element has aria-disabled set to true.
  8. Optionally, each element that serves as a container for panel content has role region and aria-labelledby with a value that refers to the button that controls display of the panel.
  9. Avoid using the region role in circumstances that create landmark region proliferation, e.g., in an accordion that contains more than approximately 6 panels that can be expanded at the same time.
  10. Role region is especially helpful to the perception of structure by screen reader users when panels contain heading elements or a nested accordion.

Accordion Example

(provided by WAI-ARIA Authoring Practices)

Button

Roles, States, and Properties

  1. The button has role of button.
  2. The button has an accessible label. By default, the accessible name is computed from any text content inside the button element. However, it can also be provided with aria-labelledby or aria-label.
  3. If a description of the button's function is present, the button element has aria-describedby set to the ID of the element containing the description.
  4. When the action associated with a button is unavailable, the button has aria-disabled set to true.
  5. If the button is a toggle button, it has an aria-pressed state. When the button is toggled on, the value of this state is true, and when toggled off, the state is false.

Button Example

(provided by WAI-ARIA Authoring Practices)

Breadcrumb

Roles, States, and Properties 

  1. Breadcrumb trail is contained within a navigation landmark region.
  2. The landmark region is labelled via aria-label or aria-labelledby.
  3. The link to the current page has aria-current set to page. If the element representing the current page is not a link, aria-current is optional.

Breadcrumb design example

(provided by WAI-ARIA Authoring Practices)

Combo Box

Roles, States, and Properties  

  1. The element that serves as the combobox container has role combobox.
  2. The element with role combobox contains or owns a textbox element that has either role textbox or role searchbox.
  3. When the combobox popup is visible, the combobox element contains or owns an element that has role listbox, tree, grid, or dialog.
  4. If the combobox popup has a role other than listbox, the element with role combobox has aria-haspopup set to a value that corresponds to the popup type. That is, aria-haspopup is set to grid, tree, or dialog. Note that elements with role combobox have an implicit aria-haspopup value of listbox.
  5. When the combobox popup is visible, the textbox element has aria-controls set to a value that refers to the combobox popup element.
  6. The textbox element has a value for aria-multiline of false. Note that the default value of aria-multiline is false.
  7. When the combobox popup is not visible, the element with role combobox has aria-expanded set to false. When the popup element is visible, aria-expanded is set to true. Note that elements with role combobox have a default value for aria-expanded of false.
  8. When a combobox receives focus, DOM focus is placed on the textbox element.
  9. When a descendant of a listbox, grid, or tree popup is focused, DOM focus remains on the textbox and the textbox has aria-activedescendant set to a value that refers to the focused element within the popup.
  10. In a combobox with a listbox, grid, or tree popup, when a suggested value is visually indicated as the currently selected value, the option, gridcell, row, or treeitem containing that value has aria-selected set to true.
  11. If the combobox has a visible label, the element with role combobox has aria-labelledby set to a value that refers to the labelling element. Otherwise, the combobox element has a label provided by aria-label.
  12. The textbox element has aria-autocomplete set to a value that corresponds to its autocomplete behavior:
    • none: When the popup is displayed, the suggested values it contains are the same regardless of the characters typed in the textbox.
    • list: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox.
    • both: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox. In addition, the portion of the selected suggestion that has not been typed by the user, known as the completion string, appears inline after the input cursor in the textbox. The inline completion string is visually highlighted and has a selected state.

Examples of ARIA 1.1 Combobox

(provided by WAI-ARIA Authoring Practices)

Dialog (Modal)

Roles, States, and Properties   

  1. The element that serves as the dialog container has a role of dialog.
  2. All elements required to operate the dialog are descendants of the element that has role dialog.
  3. The dialog container element has aria-modal set to true.
  4. The dialog has either:
  • A value set for the aria-labelledby property that refers to a visible dialog title.
  • A label specified by aria-label.
  • Optionally, the aria-describedby property is set on the element with the dialog role to indicate which element or elements in the dialog contain content that describes the primary purpose or message of the dialog. Specifying descriptive elements enables screen readers to announce the description along with the dialog title and initially focused element when the dialog opens.
  • Modal Dialog Example

    (provided by WAI-ARIA Authoring Practices)