SiteLint documentation and guidelines

Aria labelledby association

Rule

  • Audit: Accessibility
  • Standard:
  • Level:
  • Success Criteria:
  • ID: aria-labelledby-association

Description

The aria-labelledby attribute in HTML is used to associate a label with an element, providing an accessible name for the element by referencing other elements that contain the descriptive text. This attribute is crucial for accessibility, as it helps screen readers and other assistive technologies convey the purpose or meaning of the element to users with disabilities. Proper use of aria-labelledby ensures that elements are described accurately and comprehensively.

Disabilities impacted

  • Visual impairments: users with visual impairments who rely on screen readers depend on aria-labelledby to understand the context and purpose of elements.
  • Cognitive disabilities: users with cognitive disabilities benefit from clear and descriptive labels that help them understand the content and its function.
  • Motor impairments: users with motor impairments who navigate using keyboards or other assistive devices rely on properly labeled elements for efficient interaction.

Why it matters

Using the aria-labelledby attribute correctly ensures that all users, particularly those using assistive technologies, can access and understand the content. It provides a way to label elements more flexibly and comprehensively than the aria-label attribute alone, enhancing the accessibility and usability of web content.

Coding problems and solutions

Common coding problems

  • Empty referenced element: the element referenced by the aria-labelledby attribute is empty, providing no useful information.
  • Non-descriptive referenced element: the referenced element contains text that is not descriptive or meaningful.
  • Incorrect id reference: the aria-labelledby attribute references an incorrect or non-existent id.

How to fix it

Ensure referenced element contains meaningful text

Make sure that the element referenced by the aria-labelledby attribute contains descriptive and meaningful text.

Incorrect example
<label id="username-label"></label>
<input type="text" id="username" aria-labelledby="username-label">
Correct example
<label id="username-label">Username:</label>
<input type="text" id="username" aria-labelledby="username-label">

Use descriptive text in referenced elements

Provide clear and descriptive text in the element that is referenced by the aria-labelledby attribute.

Incorrect example
<p id="description">Text box:</p>
<input type="text" aria-labelledby="description">
Correct example
<p id="description">Enter your username in the text box below:</p>
<input type="text" aria-labelledby="description">

Verify correct id references

Ensure that the aria-labelledby attribute references the correct id of an existing and appropriate element.

Incorrect example
<h2 id="header">User Information</h2>
<form aria-labelledby="nonexistent-id">
    <!-- Form contents -->
</form>
Correct example
<h2 id="header">User Information</h2>
<form aria-labelledby="header">
    <!-- Form contents -->
</form>

Use multiple ids for comprehensive labels

Combine multiple ids in the aria-labelledby attribute to create a comprehensive label.

Correct example
<label id="fname-label">First Name:</label>
<label id="lname-label">Last Name:</label>
<input type="text" id="fullname" aria-labelledby="fname-label lname-label">
Incorrect example
<input type="text" id="fullname" aria-labelledby="fullname">

Known limitations

  • Dynamic content: ensure that dynamically generated content correctly implements the aria-labelledby attribute and references appropriate elements.
  • Complex documents: for complex documents with many elements, carefully plan and test the use of aria-labelledby to ensure clarity and accessibility.
  • Testing across devices: test the implementation across different devices and screen readers to ensure the aria-labelledby attribute provides the necessary information.

Resources