aria-labelledby

Relationship property from WAI-ARIA for one or more elements with a visible name (label) for another.

        
          
          <figure aria-labelledby="group-label">  <img    src="images/chart.png"    alt="Weight loss progress over 9 weeks. Initially, the hedgehog weighed 11 kilograms,    at the end — 4 kilograms."  >  <figcaption id="group-label">Weight loss chart of the hedgehog.</figcaption></figure>
          <figure aria-labelledby="group-label">
  <img
    src="images/chart.png"
    alt="Weight loss progress over 9 weeks. Initially, the hedgehog weighed 11 kilograms,
    at the end — 4 kilograms."
  >
  <figcaption id="group-label">Weight loss chart of the hedgehog.</figcaption>
</figure>

        
        
          
            
            Copy
            Copied
            Failed to copy
          
        
      

Screen readers will read the example as: “Weight loss chart of the hedgehog, group. Weight loss progress over 9 weeks. Initially, the hedgehog weighed 11 kilograms, at the end — 4 kilograms, chart.”

Assign the tag the attribute aria-labelledby with one or more IDs separated by spaces and link it to the element with the label using id.

aria-labelledby can be used for all interactive and non-interactive elements like tables and graphics, except for:

• <caption> and role caption.
• <code> and role code.
• <dd> and role definition.
• <dt>, <dfn> and role term.
• <del> and role deletion.
• <em> and role emphasis.
• <ins> and role insertion.
• <mark> and role mark.
• <p> and role paragraph.
• <strong> and role strong.
• <sub> and role subscript.
• <sup> and role superscript.
• <time> and role time.
• <span>, <div> and role generic.
• roles presentation or none and suggestion.

For <input> primarily use <label>. This HTML tag has an important feature — when clicking on the tag, focus moves to the field by default.

Also, aria-labelledby can be linked not only with visible elements but also with hidden ones using hidden, display: none or visibility: hidden. Note that the screen reader will still read the associated label for the element.

In the example, the switch has the label “Night mode” hidden, but it is still available for assistive technologies.

        
          
          <span id="label" hidden>Night mode</span><input type="checkbox" role="switch" aria-labelledby="label">
          <span id="label" hidden>Night mode</span>
<input type="checkbox" role="switch" aria-labelledby="label">

        
        
          
            
            Copy
            Copied
            Failed to copy
          
        
      

The label from aria-labelledby should be brief and clearly describe the purpose of the element. It is better not to change it dynamically, as this will confuse users.

aria-labelledby overrides other text values. For example, from aria-label or <label>. So use the attribute cautiously with certain roles and tags.

When a <table> has both <caption> and aria-labelledby, the table will get its name from the attribute, while the content of <caption> will become its description.

The order of IDs in aria-labelledby matters. The screen reader reads the labels in the order they are listed in the attribute. It also does not repeat labels if the IDs are duplicated.

In this example, when focusing on the first item, the screen reader will read: “Weight one kg”.

        
          
          <label id="label1" for="select">Weight</label><select  id="select"  aria-labelledby="label1 label1 select label2 label2">  <option value="1">1</option>  <option value="2">2</option></select><span id="label2">kg</span>
          <label id="label1" for="select">Weight</label>
<select
  id="select"
  aria-labelledby="label1 label1 select label2 label2"
>
  <option value="1">1</option>
  <option value="2">2</option>
</select>
<span id="label2">kg</span>

        
        
          
            
            Copy
            Copied
            Failed to copy
          
        
      

A label, also known as visible identifier in ARIA — is a visible name of any element, not just an input field as in HTML. An accessible name or name of the element is a brief title of the element that the screen reader announces when focused or sequentially reading all the content. It does not necessarily have to be visible to all users.

Most often, it is sufficient to associate the label with the required tag using for. For example, <label>, <caption> or <legend>.

When it is not possible to provide a label for an element in HTML, the aria-labelledby attribute comes to the rescue.

💡 aria-labelledby is very similar to <label>, which can be assigned to not only form elements.

💡 If an element’s name should only be seen by a screen reader, use aria-label.

💡 Keep an eye on support for aria-labelledby in browsers and screen readers, especially if you assign the attribute to static content.

        
          
          <section aria-labelledby="heading">  <h2 id="heading">Cats as a species</h2>  <!-- Text about cats --></section>
          <section aria-labelledby="heading">
  <h2 id="heading">Cats as a species</h2>
  <!-- Text about cats -->
</section>

        
        
          
            
            Copy
            Copied
            Failed to copy