aria-label

Widget property from WAI-ARIA, which sets an accessible name for an element.

The name from the aria-label attribute is only visible to assistive technologies and hidden from other users.

        
          
          <button aria-label="Pause">  <svg    viewBox="0 0 35 42"    width="35"    height="42"    xmlns="http://www.w3.org/2000/svg"  >    <!-- Description of the shape -->  </svg></button>
          <button aria-label="Pause">
  <svg
    viewBox="0 0 35 42"
    width="35"
    height="42"
    xmlns="http://www.w3.org/2000/svg"
  >
    <!-- Description of the shape -->
  </svg>
</button>

        
        
          
            
            Copy
            Copied
            Failed to copy
          
        
      

Assign the aria-label attribute to the tag with the desired text.

aria-label can be assigned to all interactive elements that can be interacted with. The attribute can also be used for some non-interactive elements — tables, modal windows, landmarks, or groups of elements. Just keep in mind that browsers and screen readers poorly support aria-label for static content.

There are tags and roles for which aria-label cannot be used:

• <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/none and suggestion.

The name in aria-label should be brief and not repeat the role of the element. For example, if it is the main navigation, name it "Main" instead of "Main navigation." In the latter case, the screen reader will say "Main navigation, navigation." Too many navigations! Also, try to give unique names to landmarks — parts of the page that users of screen readers can quickly jump to.

Names from aria-label can be changed dynamically, but this is a potential problem for voice control users. Such users may find it difficult to guess how the name in aria-label has changed, upon which voice commands depend. This also applies to situations where unpredictable names are used. For example, a button with a house icon is named not "Home," but "Unread messages."

Keep in mind that aria-label overrides the text content of some tags and elements with ARIA roles, as well as from ARIA attributes. The exception is another attribute aria-labelledby. It always overrides aria-label, so you shouldn't assign both to the same element.

If an element already has a visible name, it is better not to override it in aria-label. This is redundant and may confuse sighted users of screen readers. For instance, a button may have the name "Agree," but the screen reader will read a completely different text from aria-label "I accept the terms of the agreement."

        
          
          <!-- ⛔ It's better not to do this --><button aria-label="I accept the terms of the agreement">Agree</button>
          <!-- ⛔ It's better not to do this -->
<button aria-label="I accept the terms of the agreement">Agree</button>

        
        
          
            
            Copy
            Copied
            Failed to copy
          
        
      

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

The accessible name or simply the name of an element is a brief title of the element that the screen reader vocalizes when it is focused or when it reads everything in succession.

Most often, it is sufficient to add text to the element, for example, in a <button> or <a>. In the case of an image, the source of the name is alt. Other elements can get their name from title as does <iframe>.

If none of these methods can be used, the aria-label attribute is one of the additional ways to set the name of the element. It will be useful in the following cases:

• Several landmarks on the page. For example, <header> or <footer>.
• A group of elements that needs to be conveyed to assistive technologies.
• Interactive elements without textual content. For example, a button with an icon.

💡 Don’t forget to translate the content of the attribute when supporting multiple languages.

💡 The content of aria-label sometimes does not work well with automatic translation, and previously was not translated by any services at all.

💡 When an element needs to have a visible name for everyone, use aria-labelledby.

        
          
          <button>  <svg    viewBox="0 0 35 42"    width="35"    height="42"    xmlns="http://www.w3.org/2000/svg"  >    <!-- Description of the shape -->  </svg>  <span class="visually-hidden">Pause</span></button>
          <button>
  <svg
    viewBox="0 0 35 42"
    width="35"
    height="42"
    xmlns="http://www.w3.org/2000/svg"
  >
    <!-- Description of the shape -->
  </svg>
  <span class="visually-hidden">Pause</span>
</button>

        
        
          
            
            Copy
            Copied
            Failed to copy
          
        
      

        
          
          .visually-hidden {  position: absolute;  width: 1px;  height: 1px;  clip: rect(0 0 0 0);  clip-path: inset(50%);  overflow: hidden;  white-space: nowrap;}
          .visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  clip: rect(0 0 0 0);
  clip-path: inset(50%);
  overflow: hidden;
  white-space: nowrap;
}

        
        
          
            
            Copy
            Copied
            Failed to copy