aria-label / aria-labelledby / aria-describedby

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.

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>

  <!-- aria-label: give a name to an icon button -->
  <button aria-label="Search">🔍</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>

</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.

<!-- Screen reader announcement example -->
🔍 button → "Search, button"
Form      → "Login, form"
Input     → "Username, text input"
          → (on focus) "Use alphanumeric characters only."

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.

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

Home