Short note on aria-label, aria-labelledby, and aria-describedby

Posted on Wednesday, 12 July 2017 by Léonie Watson

Be careful when you use the aria-label, aria-labelledby, and aria-describedby attributes, because they do not work consistently with all HTML elements. This is a short note on when (and when not) to use those attributes.

The aria-label and aria-labelledby attributes can be used to give an element an accessible name. The aria-describedby attribute can be used to give an element an accessible description. Not all elements can be given an accessible name and/or description though.

The aria-label, aria-labelledby, and aria-describedby attributes can be used with:

  • interactive elements like a (when the href attribute is present), audio and video (when the controls attribute is present), input (unless they are of type="hidden"), select, button, and textarea
  • elements that have a landmark role – either implicit (header, footer, main, nav, aside, section, and form) or explicitly set via the role attribute
  • elements that have an explicit widget role applied using the role attribute – there are 27 widget roles in ARIA 1.1, including dialog, slider, progressbar, tooltip, and table
  • iframe and img elements

If you use aria-label, aria-labelledby, or aria-describedby with any other elements (like div, span, p, blockquote, or strong etc.), they generally won’t work across all browser/assistive technology combinations.

For more information on this, and on using ARIA with HTML in general, refer to the W3C Note on Using ARIA.

About Léonie Watson

Léonie (@LeonieWatson) is Director of Developer Communications at TPG, co-chair of the W3C Web Platform Working Group working on HTML and Web Components, writer for Smashing magazine, SitePoint.com and Net magazine, and regular conference speaker.

Comments

  1. Another important warning is that aria-label and aria-labelledby will override the visible text for certain elements, such as links and buttons. I often see developers that add labels to these with the intent of providing additional information or instructions without realizing that the link or button text will then be entirely inaccessible.

  2. @SB yes it can. The <ul> and <ol> elements map to the “list” role, which is one of the widget roles.

    @Mark Root-Wiley yes it can, though with SVG it’s almost always necessary to explicitly apply one of the landmark or widget roles using the role attribute.

Leave a Reply

Your email address will not be published. Required fields are marked *