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, and tooltip
  • 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 although not a widget role, acts like a group role. @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.

  3. I have a row of various information containing:
    An article number, the title of the article, an input field where you can input the amount you want to order, the price and a link to delete this order.
    The row above is indicating labels for this information and a user who can see, easily understands it as a table.

    Design wise it is all contained in HTML div elements. I cannot convert it into a tables, because it is a project between many companies and even though I suggested it such a change was not approved upone. But I have to make it accessible.

    I thought I could give each piece of information a proper label via aria-labelledby and the ID of the corresponding div of the row above that contains a name for this piece of information. But then I read that it’s not possible for HTML div elements.
    Does it work if I give for example the HTML div element containing the price a role of ‘cell’ and then the attribute aria-labelledby?

    Thank you very much for the help.

  4. @Miriam if you can’t change the HTML, you can use the table, row, cell, and columnheader roles to polyfill the missing table semantics.

Comments for this post are closed.