aria-label / aria-labelledby / aria-describedby

Since:		WAI-ARIA 1.1（2017）

aria-label, aria-labelledby, and aria-describedby are WAI-ARIA attributes used to associate a name (label) or description with an element for assistive technologies such as screen readers. WAI-ARIA (Web Accessibility Initiative - Accessible Rich Internet Applications) is a specification for improving the accessibility of web content.

Syntax

<!-- aria-label: specify a name directly as text -->
<button aria-label="Close menu">×</button>

<!-- aria-labelledby: specify a name by referencing another element's ID -->
<h2 id="section-title">Contact Form</h2>
<form aria-labelledby="section-title">...</form>

<!-- aria-describedby: provide supplementary description via another element's ID -->
<input type="password" aria-describedby="pw-hint">
<p id="pw-hint">Must be at least 8 characters and include letters and numbers.</p>

Attribute list

Attribute	Description
aria-label	Specifies the accessible name of an element directly as a string. Use this when no visible label is present.
aria-labelledby	References the ID of another element on the page and uses its text as the name. Multiple IDs can be provided, separated by spaces.
aria-describedby	References the ID of an element that provides supplementary information. Use this for additional details rather than a primary name or label.

Sample code

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
</head>
<body style="margin: 20px;">

  <!-- aria-label: give a name to icon buttons -->
  <button aria-label="Search">🔍</button>
  <button aria-label="Close menu">×</button>

  <!-- aria-labelledby: use a heading as the form's label -->
  <h2 id="login-title">Login</h2>
  <form aria-labelledby="login-title">
    <label for="username">Username</label>
    <input type="text" id="username" name="username"
           aria-describedby="username-hint">
    <p id="username-hint">Use alphanumeric characters only.</p>

    <label for="password">Password</label>
    <input type="password" id="password" name="password">

    <button type="submit">Login</button>
  </form>

  <!-- aria-label: distinguish multiple navigation landmarks -->
  <nav aria-label="Main navigation">
    <ul>
      <li><a href="/?lang=en">Home</a></li>
      <li><a href="/about?lang=en">About</a></li>
    </ul>
  </nav>

  <nav aria-label="Footer navigation">
    <ul>
      <li><a href="/privacy?lang=en">Privacy Policy</a></li>
      <li><a href="/terms?lang=en">Terms of Use</a></li>
    </ul>
  </nav>

  <!-- aria-labelledby: compose a label from multiple IDs -->
  <span id="qty-label">Quantity</span>
  <span id="item-name">(Cast Iron Skillet)</span>
  <input type="number" aria-labelledby="qty-label item-name" min="1">
  <!-- Screen reader announces: "Quantity (Cast Iron Skillet)" -->

</body>
</html>

Result

A screen reader announces the 🔍 button as "Search, button." The form is introduced as "Login, form." When focus moves to the username field, the reader announces something like "Username, text input, Use alphanumeric characters only." — including the supplementary hint.

View sample page

Overview

WAI-ARIA (Web Accessibility Initiative – Accessible Rich Internet Applications) is a specification for conveying the meaning of content to users who cannot perceive visual information, via assistive technologies such as screen readers. aria-label, aria-labelledby, and aria-describedby are the core attributes for associating a "name" and "description" with an element.

When choosing between aria-label and aria-labelledby: if a heading or descriptive text already exists on the page, it is recommended to reference it with aria-labelledby. Use aria-label to specify text directly on icon buttons or decorative elements that have no visible label. If both aria-label and aria-labelledby are specified on the same element, aria-labelledby takes precedence.

aria-describedby is for supplementary information, not the primary label. Use it for input hints, error messages, or any content you want read after the main announcement. When a native label element can handle the association, prefer it over ARIA — use ARIA only as a complement to standard HTML semantics.

WAI-ARIA Practical Patterns

The aria-label family of attributes is most commonly used in the following patterns.

Pattern	Attribute to Use	Example
Icon button (no visible text)	aria-label	Give a search button (magnifying glass icon) the name "Search"
Multiple navigations of the same type	aria-label	Distinguish header nav from footer nav as "Main navigation" and "Footer navigation"
Using a heading as a label	aria-labelledby	Use the heading above a form as the form's accessible name
Input field hint or note	aria-describedby	Associate a "Must be 8 characters or more" note with a password field
Error messages	aria-describedby	Associate a validation error message with the input field

<!-- Accessible error message implementation -->
<div>
  <label for="email">Email Address</label>
  <input type="email" id="email" name="email"
         aria-describedby="email-error"
         aria-invalid="true">
  <!-- role="alert" ensures dynamically added errors are announced -->
  <p id="email-error" role="alert">
    Please enter a valid email address.
  </p>
</div>

<!-- Add a description to a close button -->
<dialog aria-labelledby="dialog-title">
  <h2 id="dialog-title">Delete File</h2>
  <p>Are you sure you want to delete this file?</p>
  <button aria-label="Close dialog">×</button>
  <button>Delete</button>
  <button>Cancel</button>
</dialog>

If you find any errors or copyright issues, please contact us.

Home

HTML Dictionary