Broken ARIA Reference - Equalize Digital (2024)

Did a “Broken ARIA Reference” error appear in an Accessibility Checker audit of one of your WordPress posts or pages? Read on below for an explanation of this error, how it impacts your website’s accessibility, and how to fix it.

About the Broken ARIA Reference Error

What is ARIA?

ARIA stands for Accessible Internet Rich Applications. It is a set of attributes that can be used to create more accessible web content for individuals with disabilities and users with screen readers.

ARIA attributes can be added to HTML elements on a web page in order to fix accessibility errors that HTML alone may not be able to resolve. ARIA attributes are most frequently added to web page elements that are developed with JavaScript, however, they can be added to any type of code that needs to be made more accessible assuming that cannot be accomplished with correct HTML semantics instead.

You can learn more about ARIA on Mozilla’s developer documentation page.

What is an ARIA reference?

An ARIA reference is used to show the relationship between two elements on a page that may not be able to be otherwise determined by a screen reader or assistive technology device. ARIA references can also be used to avoid duplicating of effort in the coding of an element by pulling information from the ID of a different element automatically. The two most commonly used ARIA references are “aria-labeledby” and “aria-describedby.”

What is aria-labelledby and how should it be used?

aria-labelledbysets relationships between HTML elements and their labels. This ARIA attribute accepts one or more strings as its value, which match the IDs of HTML elements on the page from which assistive devices can take text for labeling.

Here is an example that shows how aria-labelledby can be used to add additional context in the scenario where a field on a form has multiple labels providing context to the field:

<div id="formBillingId">Billing</div><div> <div id="formNameId">Name</div> <input type="text" aria-labelledby="formBillingId formNameId"/></div><div> <div id="formAddressId">Address</div> <input type="text" aria-labelledby="formBillingId formAddressId"/></div>

The code example above communicates to screen readers that the field on this form is not just asking for an address, but is asking for a billing address. In this example, multiple element IDs have been included in the aria-labelledby attribute separated by a space, and a screen reader would then announce the information from both elements in the order that they are presented.

Mozilla has great examples of how aria-labelledby can be used on its developer website. The aria-labelledby attribute can be used to connect:

• fields with their labels.
• headings with regions.
• radio group containers with a label.
• dialogs with a header.
• definitions with terms.
• menus with a title.

Additionally, aria-labelledby can be used as an alternative to appending screen-reader only text if you’re looking for a cleaner and less repetitive way of resolving ambiguous anchor text. Here is an example of code that uses aria-labelledby to make link anchors more clear:

<h2 id="premium">About Our Premium TV Package</h2><p>This is are most expensive and highest profit package for us. You should get it.</p><a href="/moremoney.html" id="learn1" aria-labelledby="learn1 premium">Learn more</a><h2 id="ok">About Our Ok TV Package</h2><p>Sometimes "just ok" really is ok. Get this package to save money</p><a href="/cheapskate.html" id="learn2" aria-labelledby="learn2 ok">Learn more</a>

In this example, because there is a heading associated with each package, an ID can be added to the headings and the links and used in the labelledby attribute. This way we don’t have to repeat the specific package information in an aria-label nor add hidden screen reader only text that explains which package is being linked to for each “learn more” link. Instead, screen readers will build that context from what is already on the page. The end result is a person using a screen reader will hear “Learn more about our premium TV package” as the link name.

What is aria-describedby?

Thearia-describedbyattribute is, like the labelledby attribute, used to indicate IDs of elements that describe the object that contains the aria-describedby attribute.

In this way, aria-describedby is very similar to aria-labelledby. The primary difference is that aria-labelledby provides a short description of the essence of the groups or elements it is used on, whereas the describedby element is a longer description that provides more detailed information that a website user might need.

Thearia-describedbyattribute can be used to connect static text with forms, widgets, groups of elements, panes, regions that have a heading, definitions, links and more. There areexamples of aria-describedby on Mozilla’s developer websitethat provide code examples of how to use the attribute in a variety of cases if you would like to learn more.

What constitutes a broken ARIA reference?

If Accessibility Checker flags a broken ARIA reference on your WordPress site, that means that an aria-labeledby or aria-describedby element is present on the page or post but that its reference target does not exist. This means that the element that is being referred to by the specific ARIA attribute you’re using either does not have a proper label or descriptor, or it is not present on the page. Sometimes this is a result of a typo in the code or it is a result of JavaScript or other code hiding the element to which the ARIA attribute is referring.

How does Accessibility Checker test for broken ARIA references?

While auditing your page or post content, Accessibility Checker will look at all of the elements, including those with explicit ARIA attributes. If an aria-labeledby or aria-describedby attribute is present and not empty, Accessibility Checker will scan the post or page to attempt to find the referred to ID. If the ID cannot be found, a broken ARIA reference will be flagged and added to the list of accessibility errors on your website.

Impact on Accessibility

Why are ARIA references important?

ARIA references are important because they allow users with screen readers to understand relationships between elements that they would not be able to otherwise perceive.

On forms, for example, screen reader users frequently tab through input fields so that they can quickly complete the form. ARIA labels can be used to connect the form fields with the field labels so that screen readers will announce the purpose of each field as it is tabbed into, as shown in the prior code example for a billing address field.

Problems caused by broken ARIA references

If an ARIA reference target is missing, a screen reader will not pick up on these relationships, and a user can miss out on key information.

In the prior code example with the billing address fields, without the aria-labelledby element, a screen reader user would only hear the word “Edit” or “Edit blank, type in text” or something similar depending upon which screen reader they’re using. This would occur when tabbing through inputs even if a visible field label is present as the screen reader would not know which label is for which field. Without the field to label connection, assistive technology users would need to back up to the previous element to find out what the field is for and might still question if they were filling out the form correctly.

Ensuring that ARIA references have proper labels and existing targets within a web page will ensure that screen reading users will be able to understand and engage with all the aspects of that page.

Relevant WCAG 2.1 Success Criteria

1.3.1 Info and Relationships – Level A

This guideline requires that information,structure, andrelationshipsconveyed throughpresentationcan beprogrammatically determinedor are available in text.

4.1.2 Name, Role, Value – Level A

This guideline requires that alluser interface components,including but not limited to form elements, links, and components generated by scripts, must:

• have anameandrolethat can beprogrammatically determined;
• in the case of states, properties, and values that can be set by the user, be able to beprogrammatically set; and
• announce notifications of changes to these items toall user agents, includingassistive technologies.

How to Fix a Broken ARIA Reference

What to do (in short)

To fix a broken ARIA reference, you will need to find the ARIA elements that are being flagged, and ensure that their reference targets are present and properly labeled.

This may mean that the identifying attribute of the reference target needs to be changed to reflect the ARIA element. If the reference target is missing from the page altogether, you will need to create a reference target with the correct ID.

How to find broken ARIA references on your WordPress post or page and fix them

First, install thefreeAccessibility Checker WordPress plugin.

For any pages or posts that have a Broken ARIA Reference error in the WordPress editor, you can open the details tab in the Accessibility Checker meta box, then expand the Broken ARIA Reference error to see a list of code that caused the error to be flagged.

In the screenshot above, you can see the line of code that triggered a Broken ARIA Reference error in Accessibility Checker’s audit of the post or page. In this example the error was flagged on this heading:

<h5 aria-describedby="random123">SIMPLE AND EFFECTIVE EMAIL SUBSCRIBE</h5>

If this were your website, you would need to look at the ID of the element that you believe this element should reference and make sure that the element has an ID of “random123.” If it does not have that ID, then you would either need to change its ID to “random123” or you would need to change the aria-describedby attribute that is on the heading to match the correct ID of that element.

If there is nothing on the post or page that this heading is supposed to reference, you would either need to add something and give it an ID of “random123” or you would need to delete aria-describedby="random123" from the heading so that it no longer looks for a non-existent element.

Setting IDs in WordPress

You can find or add IDs to any element within the code editor of any page or post or by adding an HTML anchor under the Advanced block settings for just about any block in the Gutenberg block editor.

IDs must be unique within the page or post and are case sensitive. To learn more about IDs (a.k.a. HTML anchors) visit the Page Jumps support article on WordPress.org. If you edit your page using a page builder and not the default WordPress editor, please reference the documentation for that page builder to find out how to view and edit IDs on your web pages.

A note about ARIA problems and WordPress plugins

Depending upon how you’re adding content to your WordPress website, it is likely that you may encounter a broken ARIA reference that is being inserted into your post or page by a third-party plugin (such as your form plugin). If this is the case, you may not be able to correct the error.

If you encounter accessibility errors that are caused by a third-party plugin you cannot control, please reference “What to do if a Plugin You’re Using has Accessibility Errors” for ideas on how to proceed.