Fixing links and buttons with no accessible name

Why names matter

A screen reader user can pull up a list of all links or buttons on a page. A list full of "click here", "read more" and unnamed items is useless. Voice-control users also select controls by saying their names. The relevant criteria are 2.4.4 Link Purpose (In Context), 4.1.2 Name, Role, Value and 2.5.3 Label in Name.

Common failures and fixes

1. Icon-only buttons

<!-- Before: a screen reader announces just "button" -->
<button><svg>...</svg></button>

<!-- After -->
<button aria-label="Open menu"><svg aria-hidden="true">...</svg></button>

2. Links that wrap only an image

<!-- Before: no name -->
<a href="/sale"><img src="sale.jpg"></a>

<!-- After: alt text names the destination -->
<a href="/sale"><img src="sale.jpg" alt="Shop the autumn sale"></a>

3. "Click here" and "Read more"

<!-- Before -->
<p>Our returns policy changed. <a href="/returns">Click here</a>.</p>

<!-- After -->
<p>Our <a href="/returns">returns policy</a> changed.</p>

<!-- When a card layout needs "Read more", name what it is for -->
<a href="/post-1">Read more<span class="visually-hidden"> about our spring range</span></a>

4. Clickable divs

<!-- Before: not focusable, no role -->
<div onclick="addToCart()">Add to cart</div>

<!-- After: a real button gets role, focus and keyboard support for free -->
<button type="button" onclick="addToCart()">Add to cart</button>

Match the visible label

WCAG 2.5.3 asks that the accessible name contains the visible text, so a voice user who says "Search" can activate a button that shows "Search". If the visible label is "Search", do not set aria-label="Find products"; use aria-label="Search products" or leave it alone.

A quick test

Read your page's links out of context: would each one make sense if it were the only thing you heard? Open a screen reader's links list to see them in one place, as described in the hand-testing steps. Scanners reliably find empty links and buttons; judging whether the wording is clear still needs a person.

Link or button? Pick by what it does

A link goes somewhere (another page, a section, a file). A button does something (submits, opens a menu, adds to cart). Screen reader users hear the role announced, so a link that behaves like a button, or the reverse, is confusing. If it changes the address bar, use a; if it runs an action on the page, use button.

Links that open new tabs or download files

Tell people before they click. Add "(opens in a new tab)" or "(PDF, 2 MB)" to the link text, or use a visually hidden span, so no one is surprised by a new window or a download. Use target="_blank" sparingly, and when you do, add rel="noopener".

Repeated identical links

A product grid with ten "Quick view" buttons sounds identical in a links list. Add the product name to each accessible name, for example aria-label="Quick view: Navy canvas sneaker", keeping the visible words inside the label.

How assistive technology builds a name

Every link and button has an accessible name, the label that a screen reader reads and that voice control users speak. The browser works the name out in a set order. First it looks for an explicit label from aria-labelledby or aria-label. Then it uses the visible text inside the element, or an alt attribute on an image inside it. Last it may fall back to a title attribute. If none of these produces anything, the element has no name, and a scanner will report it.

The simplest and most robust approach is to put real text inside the link or button. Use hidden text or an aria-label only when a visible label would clutter the design, as with an icon.

Examples of icon buttons and links

<!-- Fails: no name -->
<button><svg>...</svg></button>

<!-- Passes: hidden text -->
<button><svg aria-hidden="true">...</svg><span class="visually-hidden">Open cart</span></button>

<!-- Passes: aria-label -->
<button aria-label="Open cart"><svg aria-hidden="true">...</svg></button>

Rewriting vague link text

When the visible label and the name differ

A common mistake is to add an aria-label that says something different from the visible text. A button that shows "Buy" but is labeled "Add item to basket" works for screen reader users but can fail for people who use voice control, who say what they see. WCAG 2.5.3 asks that the name include the visible text. If you need extra context, add it after the visible words, for example "Buy – Blue mug".

Links that look like buttons and buttons that look like links

Choose the element by what it does. A link goes somewhere: another page or a place on the same page. A button does something: submits a form, opens a menu, adds to a cart. Screen reader users hear the difference and expect it. Using a link for an action, or a button for navigation, confuses them and can break expected keyboard behavior, since links respond to Enter and buttons respond to Enter and Space.

Navigation menus and footers

Footers often hold dozens of links, and many of them are icons, such as social media buttons. Each icon link needs a name that says where it goes, such as "Instagram" or "Follow us on Instagram". Wrapping the footer links in a navigation landmark with a label, such as "Footer", lets screen reader users jump to it. Avoid repeating identical link names that go to different places.

A five-point checklist

1. Every link and button has visible text, or an accessible name for an icon.
2. The name says what the link does or where it goes, without needing the surrounding text.
3. Links to files tell the user the type and size.
4. Links that open a new tab say so.
5. No two different links share the same name on a page.

A worked example: a blog index page

A blog index lists twelve posts, each with a title, a short summary and a "Read more" link. A screen reader user who opens the links list hears "Read more" twelve times and has no idea which post each belongs to. There are two ways to fix this. The first is to make the post title the link and remove the Read more link. The second is to keep the link and extend its name with hidden text, such as "Read more about how to choose a water filter". Both give each link a distinct name, and the first also gives sighted visitors a larger target.

Names for common interface elements

Why the title attribute is not enough

The title attribute shows a tooltip on hover with a mouse. It does not appear for keyboard or touch users, it is not announced consistently by screen readers and it cannot be zoomed. Treat it as extra, never as the only name. Put the name in visible text, or in an aria-label if the design has no room for words.

Buttons that change state

Some buttons toggle: they open a menu, expand a section or mark an item as a favorite. For these, expose the state. A menu button should announce whether the menu is expanded, using aria-expanded. A favorite button should announce whether it is pressed, using aria-pressed. Without them, a screen reader user hears the name and cannot tell what happened after pressing it. Keep the name stable, so the button does not change from "Menu" to "Close menu" at the same time as the state changes, which can be announced twice.

<button aria-expanded="false" aria-controls="filters">Filters</button>
<div id="filters" hidden>...</div>

A short audit of your own page

1. Open the links list in your screen reader or a browser extension and read through it.
2. Mark any link whose purpose is not clear on its own.
3. Check every icon button for a name.
4. Check for several links that share a name but go to different places.
5. Fix and retest.

A worked example: fixing a store header

A store header contains a logo link, a search icon, an account icon, a wishlist heart and a cart bag with a number. A scan reports four buttons and links with no accessible names. The logo link is also reported because the image inside it has no alt text.

The developer gives the logo image alt text "Harbor Outfitters, home", adds aria-label values "Search", "Account", "Wishlist" and "Cart, 2 items" to the icon controls, and updates the cart label when the count changes. The icons themselves are hidden from assistive technology so they are not announced twice. The visual design does not change. A screen reader user now hears a sensible sequence at the top of every page, and voice control users can say "click Cart".

Names in other languages

If your site is translated, the accessible names must be translated as well. A hidden label in English on a French page is read with a French voice, which sounds wrong and is hard to understand. Check icon labels, hidden text and aria-label values when you add a language, because they are often missing from translation files.

Review checklist for editors

1. Read each link aloud without the surrounding text. Does it still make sense?
2. Avoid starting with filler such as "link to" or "go to".
3. Keep link text unique when destinations differ.
4. Do not use a raw web address as link text unless that is the point.
5. Add the file type and size when linking to a download.
6. Say so when a link opens in a new window.

More questions about link and button names

• Can I use the same link text twice? Yes, if both links go to the same place. Different destinations need different names.
• What if my design calls for "Read more"? Keep the visible text and add hidden context, such as "Read more about winter coats".
• Is an image link treated differently? The alt text of the image becomes the link's name, so it should describe the destination.
• Should I mention that something is a link or a button? No. Screen readers announce the role.
• Does link text matter for SEO? Descriptive text helps both people and search engines. See accessibility and SEO.

In short

A good name says what will happen when you activate the element, in as few words as possible. It matches what is shown on screen and stays the same across the site for the same action. If you check only these three points, you will fix most of the naming issues a scanner reports.

Short, specific names help everyone. They make menus faster to scan, they make links easier to find again and they make your content clearer to people who read it out of order.

When you fix a name in a shared component such as a header, footer or product card, the fix applies everywhere that component is used. Start there, since a handful of changes can clear a large share of the naming issues on the whole site.

Then check the pages that editors build by hand, where vague link text tends to creep in, such as blog posts, landing pages and promotional banners.

Link text in emails and social posts

The same rule applies outside your website. In a newsletter, a line such as "See this month's offers" works as a link on its own, while a bare web address is read out character by character by some screen readers. On social platforms, put the link in the post with a short lead-in, and use the platform's alternative text field for any image. Writing links this way takes no extra time and makes each message easier for everyone to scan.

Test with the links list

Open your screen reader's list of links (VoiceOver rotor on Mac, or NVDA's elements list on Windows) and read it top to bottom. Every entry should make sense on its own. Do the same for the buttons list.