Accessible Names

Imagine walking into a room where every door, drawer, and switch has no label. You could still open things, but you would have to guess what each one does. That is what a page feels like to a screen reader user when controls have no accessible name.

An accessible name is the short piece of text that assistive technology uses to call something by its name. "Save recipe, button." "Email address, edit text." "Close, button." The name is what a screen reader announces, what a voice control user says to click something, and what shows up in lists of links and form fields. It is one of the most important parts of an accessible page, and one of the easiest to get right.

What You Will Learn

• What an accessible name is, and how it differs from a description
• Where browsers get names from, and in what order
• How names work for buttons, links, form fields, images, landmarks, and iframes
• Why the visible label must be part of the name (WCAG 2.5.3)
• How to write good names: short, unique, and meaningful
• How to check names in your browser

The Big Idea

HTML Code

index.html

<!-- Names from content -->
<button type="button">Save recipe</button>
<a href="/recipes">All recipes</a>

<!-- A name from a label -->
<label for="email">Email address</label>
<input id="email" type="email" autocomplete="email">

<!-- A name from alt text -->
<img src="loaf.jpg" alt="A round sourdough loaf with a deep golden crust">

<!-- An icon-only button needs a name you add yourself -->
<button type="button" aria-label="Search recipes">
  <span aria-hidden="true">🔍</span>
</button>

<!-- Two navigation areas need different names -->
<nav aria-label="Main">…</nav>
<nav aria-label="Footer">…</nav>

<!-- An iframe is named by its title -->
<iframe src="/map" title="Map of our bakery"></iframe>

Name Lab

http://127.0.0.1:5500/index.html

Pick each example in the lab, read the name, then edit the HTML and watch the name change. Try deleting the aria-label from the icon button, or adding a title to the image.

What Is an Accessible Name?

Every element in the accessibility tree has a role (what it is), a name (what it is called), and sometimes a state or value (what it is doing). Together they tell a person what a control is and what it does.

• Role: button
• Name: "Save recipe"
• State: pressed, expanded, checked, and so on

The name is not the same as a description. A name is short and identifies the thing ("Password"). A description gives extra help ("At least 12 characters"). You will learn to add descriptions with aria-describedby later in this section.

info

A screen reader reads the name and the role together, in an order that depends on the screen reader. If your name says "Search button," many users will hear "Search button, button." Name the action, and let the role speak for itself.

Where Names Come From

The browser works out the name from several possible sources, and uses the first useful one. This is a simplified version of the order:

Order	Source	Example
1	aria-labelledby	<button aria-labelledby="title">
2	aria-label	<button aria-label="Close">
3	The element's native label	<label>, alt, <legend>, <caption>, a button's value
4	The element's content (for buttons, links, headings, tabs, menu items)	<button>Save recipe</button>
5	The title attribute	<a href="/" title="Home">
6	The placeholder (a weak fallback)	<input placeholder="Email">

The real rules (called the Accessible Name and Description Computation) have more steps, and browsers apply a few small differences. But this order covers nearly everything you will meet.

tip

The best name is almost always the one that is already on the screen. Use real text and real labels first. Reach for aria-label only when there is no visible text to use. The next lessons look at aria-label and aria-labelledby in detail.

Names From Content

Buttons, links, headings, tabs, and menu items are named by what is inside them.

<button type="button">Save recipe</button>   <!-- name: Save recipe -->

<a href="/sourdough">
  <img src="loaf.jpg" alt="">
  Sourdough loaf
</a>                                         <!-- name: Sourdough loaf -->

Notice the image in the second example has alt="". It is decorative (the text already says it), so it adds nothing to the name. If the image were the only content, its alt text would become the link's name, and it would need to describe where the link goes.

An icon with no text is the classic failure:

<!-- Bad: no name at all -->
<button type="button"><span class="icon-search"></span></button>

<!-- Good: a name for the action -->
<button type="button" aria-label="Search recipes">
  <span class="icon-search" aria-hidden="true"></span>
</button>

Another good option is visually hidden text inside the button. It stays in the page for screen readers, but is not drawn on screen. Your CSS framework probably has a ready-made class for this, often called sr-only or visually-hidden.

Names From Labels

Form fields get their names from a label element. This is the best way, because the label also makes the clickable area bigger and is visible to everyone.

<!-- Connected with for and id -->
<label for="email">Email address</label>
<input id="email" type="email">

<!-- Or wrapped around the field -->
<label>
  Email address
  <input type="email">
</label>

A placeholder is not a label. It vanishes as soon as you type, it often has weak contrast, and many tools treat it only as a last resort. Use it for an example of the format (name@example.com), never for the label itself. See Accessible Forms for more.

For a group of related fields (such as a set of radio buttons), use fieldset with a legend. The legend gives the group its name, and a screen reader reads it with each option: "Delivery: Standard, radio button."

Names for Images

For an img, the name is its alt text.

• Informative image: write a short description of its purpose or content.
• Decorative image: use alt="", so assistive technology skips it.
• Image that is a link or button: the alt text should describe where the link goes or what the button does, not the picture.
• Missing alt: some screen readers read out the file name, such as "IMG underscore 4021 dot jpg." Always include the attribute.

You will study this in depth in the next lesson, Alt Text.

Names for Landmarks, Frames, and Tables

• Landmarks: if you use more than one of the same kind (two nav elements, say), give each a different name with aria-label or aria-labelledby. Do not put the role in the name: use "Main," not "Main navigation," because the screen reader already says "navigation."
• Iframes: use the title attribute to say what the frame holds, for example title="Map of our bakery".
• Tables: give each table a caption. See Accessible Tables.
• Groups: use fieldset and legend, as above.

Label in Name: Match What People See

WCAG success criterion 2.5.3 (Label in Name) says that, if a control has a visible label, the accessible name must contain that visible text.

Why? Because voice control users say what they see. If the screen shows "Search," they say "click Search." If the hidden name is "Find recipes," nothing matches, and the command fails. A screen reader user who has sighted colleagues, or who uses speech and sight together, gets confused in the same way.

<!-- Bad: the name does not include the visible text -->
<button type="button" aria-label="Find recipes">Search</button>

<!-- Good: the visible text comes first -->
<button type="button" aria-label="Search recipes">Search</button>

The lab above has an example for this. Try it, and then fix it.

Writing Good Names

1. Be short. A name is a label, not a sentence. Put long help in a description.
2. Name the action or purpose, not the shape ("Close," not "X" or "Cross icon").
3. Make it unique. Several "Read more" links are hard to tell apart in a list of links. Say "Read more about Rye."
4. Put the key words first. Screen reader users often skim by the first word or two.
5. Do not repeat the role. "Close," not "Close button."
6. Match the visible text (see above).
7. Do not rely on title or a placeholder for names that matter.
8. Do not use the same name for different things, such as two buttons that both say "Delete" without saying what they delete.
9. Keep it in the language of the page, and translate it with the rest of your text.

Audit the Names on Your Page

A quick way to find missing names is to list every control and check it. The tool below does this for a snippet of HTML, and flags missing names, placeholders used as labels, duplicate names, and unnamed landmarks.

HTML Code

index.html

<nav aria-label="Main">
  <a href="/">Home</a>
  <a href="/recipes">Recipes</a>
</nav>
<nav aria-label="Legal">
  <a href="/privacy">Privacy</a>
</nav>

<h2>Sourdough</h2>
<a href="/sourdough" aria-label="Read more about Sourdough">Read more</a>

<button type="button" aria-label="Search recipes">
  <span aria-hidden="true">🔍</span>
</button>

<label for="mail">Email</label>
<input id="mail" type="email">

<img src="loaf.jpg" alt="A round sourdough loaf">
<img src="divider.png" alt="">

<iframe src="/map" title="Map of our bakery"></iframe>

Name Audit

http://127.0.0.1:5500/index.html

Start with the messy page, then switch to the fixed one and compare. Notice that the fixed "Read more" links use aria-label, but their visible text ("Read more") is still at the start of the name. That keeps Label in Name satisfied.

Check Names in Your Browser

You do not need a screen reader for a first check:

1. Open your browser's DevTools, and select an element.
2. Find the Accessibility panel (in Chromium-based browsers it is next to "Styles," and in Firefox it has its own tab).
3. Look at the Name and Role. If the name is empty, you have found a problem.
4. Many browsers also show where the name came from, such as "aria-label" or "contents."
5. Then, try it with a real screen reader and with voice control ("click Subscribe"), at least on your most important pages.

Good Habits

1. Use real text and real labels first. Add ARIA only when you must.
2. Give every control, image, frame, and repeated landmark a name.
3. Name icon-only controls, and hide the icon itself with aria-hidden="true".
4. Make visible text part of the name.
5. Make names unique and meaningful on their own.
6. Keep names short. Put the extra detail in a description.
7. Check the Accessibility panel whenever you build a new component.
8. Test with voice control (say what you see), not only with a screen reader.

Accessibility Checklist

• Every link, button, and form field has an accessible name.
• Every form field has a visible label (not only a placeholder).
• Every informative image has useful alt text, and decorative images use alt="".
• Icon-only controls have a name that describes the action.
• When the page has more than one of the same landmark, each has a unique name.
• Every iframe has a title, and every data table has a caption.
• Visible labels are part of the accessible names (WCAG 2.5.3).
• Links and buttons that look the same but do different things have different names.
• Names do not repeat the role ("Close," not "Close button").
• Names are written in the language of the page.

Security and Privacy Notes

• Do not put private data in names. Accessible names can be read aloud, shown in lists, and picked up by browser extensions and screen readers around other people. Do not include account numbers, full email addresses, or health details in an aria-label unless it is necessary.
• Do not use names to mislead. A name that says "Cancel" on a button that actually confirms a payment is deceptive, and breaks trust for every user.
• Be honest about links that leave your site. A name such as "Pay now" for a link to another site hides where the person is going. Say so where it matters.
• Do not collect assistive technology usage. Detecting that someone uses a screen reader, to change what you show or to track them, reveals a disability. Avoid it.
• Third-party widgets (chat, ads, embeds) often ship with missing names. Check them, and name the frame with a clear title.

Global Audience Notes

• Translate your names. Text in aria-label, alt, and title is part of your content. Make sure your translation process includes these attributes. Some automatic page-translation tools may not translate every attribute, so test with the tools your audience uses.
• Set the page language with lang (and use lang on any phrase in another language), so screen readers pronounce names correctly.
• Right-to-left languages: the accessible name follows the language of the text. Keep names in the same language as the visible label, and test with a right-to-left layout.
• Voice control works in many languages, and users say the visible label in their own language. That is another reason to keep the visible text in the name.
• Names can get longer when translated. Short, clear source names are easier to translate and to hear.
• Avoid names that only work in one culture, such as jokes, idioms, or symbol names ("Hamburger menu"). Use "Menu."

Common Mistakes to Avoid

1. Icon buttons with no name.
2. Inputs with only a placeholder.
3. Many links called "Read more" or "Click here."
4. Images with no alt attribute.
5. A name that does not contain the visible text.
6. Repeating the role in the name ("Search button").
7. Using title as the main label.
8. Several nav landmarks with no names.
9. Iframes with no title.
10. Using aria-label on elements that cannot be named (for example, a plain div or span with no role).
11. Empty headings, links, or buttons (for example, ones that only contain an icon font).
12. Never looking at the Accessibility panel.

Practice Time

Try these in your browser and your editor:

1. Use the name lab with every example, and write down the source of each name.
2. Remove the aria-label from the icon button, and watch the name disappear.
3. Fix the "Label in Name" example so the visible text is in the name.
4. Run the audit on the messy page. Fix every problem, and re-run it.
5. Paste a form from your own project into the audit, and see which fields lack names.
6. Open DevTools on a site you use, and find three controls whose names are weak.
7. Rename three "Read more" links so each one makes sense on its own.
8. Add a caption to a table and a title to an iframe, and check them in the Accessibility panel.
9. Try voice control on your computer or phone, and say the visible name of a button.
10. Bonus: write the names for a small toolbar of five icon buttons. Can you read them as a list?

Check Yourself

Choose an answer for each question, and read the explanation.

http://127.0.0.1:5500/index.html

1. A button shows only a magnifying-glass icon. What should its accessible name be?

button Search magnifier.svg

2. A text field has a placeholder that says Email, and no label. Is that enough?

Yes, the placeholder is the name No, use a real label element Yes, but only on phones

3. A button has aria-label="Find recipes" but the visible text is Search. What is the problem?

Nothing, aria-label always wins The visible text is not in the name, which breaks voice control (WCAG 2.5.3) aria-label cannot be used on buttons

4. Which source wins if an element has both aria-labelledby and aria-label?

aria-label aria-labelledby Whichever comes first in the HTML

5. A page has two nav landmarks. What do they need?

Different names, such as Main and Footer Nothing, landmarks never need names The word navigation in their names

6. Three links all say Read more. What is the best fix?

Make them bold Give each a unique name, such as Read more about Rye Remove the links

Score: 0 of 6 (0 answered)

Quick Recap

Click a question to check your answer.

1. What is an accessible name?

The short text that assistive technology uses to identify an element, such as "Save recipe" for a button. It is announced by screen readers and used by voice control.

2. In what order does a browser look for a name?

Roughly: aria-labelledby, then aria-label, then the native label (label, alt, legend, caption), then the element's content, then title, and finally placeholder as a weak fallback.

3. How do you name an icon-only button?

Add a name that describes the action, with aria-label or visually hidden text, and hide the icon itself from assistive technology with aria-hidden="true".

4. What does "Label in Name" (WCAG 2.5.3) require?

When a control has visible text, the accessible name must contain that text, so that voice control users can say what they see.

5. Why is a placeholder not a good label?

It disappears when typing, often has low contrast, and is treated only as a last-resort name. Use a real label element.

6. How should you name two nav landmarks on one page?

Give each a different name, such as aria-label="Main" and aria-label="Footer", without repeating the word "navigation."

Key Takeaways

• An accessible name is what a control is called by assistive technology, and by voice control.
• Names come from aria-labelledby, aria-label, native labels, content, title, and (as a last resort) placeholders, roughly in that order.
• Use visible text first. Add ARIA only when there is nothing visible to use.
• Every link, button, field, image, frame, and repeated landmark needs a name.
• Visible text must be part of the name (WCAG 2.5.3).
• Good names are short, unique, meaningful on their own, and do not repeat the role.
• Check names in the Accessibility panel, and test with real assistive technology.

Next, learn how to describe images well in Alt Text.