Accessible names and descriptions

Hey ,

I'm thrilled to help you learn JavaScript. Unfortunately, you've landed on a page where you cannot access with your current purchase.

Please upgrade (use this link) access this content.

I'm super eager to help you learn more!

Accessible names and descriptions

All interactive elements must have an accessible name. Screen readers will announce this name to readers.

If you want to give users more information, you can add an accessible description.

Providing an accessible name

There are three ways to give an element an accessible name:

  1. Using the text content
  2. aria-labelledby
  3. aria-label

Using the text content

The text content of an element is an accessible name. If screen reader reads the element, it’ll read the contents, plus the role of the element.

For example, if you write “submit” in a <button>, submit is the accessible name.

<button>Submit</button>

You should use text content to create accessible names whenever possible. If you cannot use text content, you can still use aria-labelledby or aria-label.

Using aria-labelledby

aria-labelledby lets you use another element as an accessible name. It takes in the id of the target element.

Here’s an example. Let’s say you have an <article> element. You can provide screen readers with the article’s name with aria-labelledby.

<article aria-labelledby="article-title">
  <h2 id="article-title">The Story of Goldilocks and the Three Bears</h2>
</article>

Note: NVDA doesn’t announce <article>.

Using aria-label

aria-label is a third way to give elements an accessible name. The accessible name is the value given to aria-label.

It should be used when:

  1. You can’t use textContent
  2. It is difficult to use aria-labelledby

When you use aria-label, screen readers will read value in aria-label. They will not read the text content.

<button aria-label="Close menu"> X </button>

Providing an accessible description

Screen reader users may skip around content with keyboard shortcuts. For example, they may Tab into a password field without going through any hints provided to a sighted user.

<form>
  <label for="password">Password</label>
  <p id="hint">Passwords should have at least one uppercase character.</p>
  <input type="password" id="password" placeholder="••••••••">
</form>

In this case, the screen reader user won’t know the password needs an uppercase character.

You can provide this (important, but easily missed) information with aria-describedby.

aria-describedby works like aria-labelledby. You pass in the id of the description into aria-describedby.

<form>
  <label for="password">Password</label>
  <p id="hint">Passwords should have at least one uppercase character</p>
  <input
    type="password"
    id="password"
    placeholder="••••••••"
    aria-describedby="hint"
  >
</form>

Important note

aria-label, aria-labelledby, and aria-describedby can only be used on elements with landmark and widget roles.

Screen readers may not speak the accessible name or description if you use them on other roles.