--- title: "Correct use of ARIA in HTML" date: "2024-10-25T09:43:20+00:00" summary: "Learn how to correctly implement ARIA in HTML for improved web accessibility and better user experience." image: type: "page" url: "/web-governance/correct-use-aria-html" id: "3cc2ea66-2153-4eaf-b03f-e8fdc32b0965" --- Table of contents will be added 4.1.2 Name, Role, Value Introduction ------------ This document provides information about the related Acquia Web Governance accessibility checks: * Element with role attributes is missing required states or properties. * Incorrect use of ARIA state or property. * Role attribute is missing a valid value. * ARIA state or property has invalid value. What ---- When you add ARIA (Accessible Rich Internet Applications) codes to a website, it is important to follow the rules for ARIA usage. ARIA are codes that can be added to website elements to improve accessibility beyond what can be achieved with the HTML code that is typically used to build webpages. When an ARIA role is added, the associated states and properties must be used correctly. When you use ARIA states and properties, you must assign valid values to them and ensure that they are applicable to the elements to which they are assigned. When you use the ARIA `role` attribute, it must be given a valid value. Why --- The use of ARIA code typically changes how the elements in a website are conveyed to the user by assistive technologies. For example, an ARIA code can alter what is read aloud when a visually impaired user navigates the page with screen reader software. This can make the difference between an element read aloud as a list of items or presented as tabs in a tabbed structure. This distinction is crucial for the user to understand how to interact with the content on the page. If the page contains ARIA codes that do not follow the guidelines for using ARIA, it is a strong indication that the developer intended to improve accessibility but something went wrong in the process. In the worst case, incorrect use of ARIA can mean that some users are unable to perceive or interact with the affected elements on the website. Who --- ### Affected users This check affects the following users who have: * Visual impairments: Who access the site contents with a screen reader or screen magnification software. * Mobility impairments: Who navigate the page with speech recognition software. ###  User story ![Woman smiling while doing yoga, with a child playfully climbing on her back in a cozy living room.](https://acquia.widen.net/content/ab902dae-f391-4c4d-a431-77ca08d2adc6/web/Mon_AccessibilityHelpCenter-UserStory-WomanDoingYogaWithGirl.png) Bridgit is a blind mother to a five-year-old girl and an 11-year-old boy: _“Honestly, there are so many times when I am shopping online, and I found exactly what I want to buy. I have spent a ton of time picking it out, going through everything, and then when I get to the very end, ready to pay, that 'Accept terms and conditions' box pops up. My screen reader tells me it is a checkbox, but when I try to click it, nothing happens. It just keeps telling me I have not checked it. It is so frustrating because I know that sometimes it actually gets marked, even though I cannot see it with my screen reader, but other times it does not work at all. It is incredibly annoying.”_ Examples -------- This section provides some examples of the issue. ### Example: Checkbox including the required aria-checked state In this example, the developer has chosen not to use a standard HTML checkbox but instead has created their own version. Here, the ARIA attributes convey to assistive technologies that the element functions as a checkbox (with the `role` attribute) and indicate whether or not the checkbox is currently checked (with the `aria-checked` attribute). ![A checkout flow in a web shop is showing. The user has ticked a checkbox with the label "Accept terms and conditions". A screen reader is showing announcing the following: Accept terms and conditions, checkbox, checked.](https://acquia.widen.net/content/3aca94e9-7401-44a2-b615-0d92461e5eeb/web/Mon_AccessibilityHelpCenter_example_form_checkbox_aria_correct.png) Screen reader software announces "Accept terms and conditions, checkbox, checked." This allows screen reader users to understand and interact with the checkbox effectively. ### Example: Checkbox missing the required aria-checked state In this example, the developer has chosen not to use a standard HTML checkbox but instead has created their own version. Here, the ARIA attributes are used to convey to assistive technologies that the element should be recognized as a checkbox (with the `role` attribute). Unfortunately, the developer forgot to include the required `aria-checked` state in the implementation. ![A checkout flow in a web shop is showing. The user has ticked a checkbox with the label "Accept terms and conditions". A screen reader is showing announcing the following: Accept terms and conditions, checkbox.](https://acquia.widen.net/content/939b281b-9486-4402-866c-8f0c15374efe/web/Mon_AccessibilityHelpCenter_example_form_checkbox_aria_incorrect.png) Screen reader software announces "Accept terms and conditions, checkbox." This means that screen reader users will miss the important information that the checkbox is currently checked. How --- #### How to identify it The Acquia Web Governance platform flags instances where the `role` attribute is used with an invalid value, where the `role` attribute is used without required states or properties, and cases where ARIA states or properties have been assigned an invalid value or are assigned to an inapplicable element. In your HTML code: * Roles will appear as `role="rolename"`. * States and properties will appear as `aria-xyz="value"`. #### How to fix it For cases of "Element with role attribute has required states and properties" look up the role in the [WAI-ARIA reference documentation](https://www.w3.org/TR/wai-aria-1.2/). In the "Required States and Properties" section, you can see which states and properties are required for that role. Adjust your code accordingly. For cases of "state or property has valid value" look up the state or property in the [WAI-ARIA reference documentation](https://www.w3.org/TR/wai-aria-1.2/). In the "Value" section, you can see which values are valid for the state or property. Adjust your code accordingly. For cases of "ARIA state or property is permitted" refer to the [ARIA in HTML](https://www.w3.org/TR/html-aria/) reference documentation for info on which states and properties are allowed for specific HTML elements. Adjust your code accordingly. For cases of "Role attribute has valid value," look up the list of allowed role names in the [WAI-ARIA reference documentation](https://www.w3.org/TR/wai-aria-1.2/). Adjust your code accordingly. Additional resources -------------------- ### WCAG success criteria * [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) ### ACT rules Related accessibility conformance testing rules: * [Element with role attribute has required states and properties](https://www.w3.org/WAI/standards-guidelines/act/rules/4e8ab6/proposed/) * [ARIA state or property is permitted](https://www.w3.org/WAI/standards-guidelines/act/rules/5c01ea/proposed/) * [Role attribute has valid value](https://www.w3.org/WAI/standards-guidelines/act/rules/674b10/proposed/) * [State or property has valid value](https://www.w3.org/WAI/standards-guidelines/act/rules/6a7281/proposed/) ### Other resources * [WAI-ARIA 1.2 Reference Documentation](https://www.w3.org/TR/wai-aria-1.2/) * [ARIA in HTML](https://www.w3.org/TR/html-aria/) * [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)