Alt text for linked images, icons and buttons

When an image sits inside a link or a button, its alt text stops being a description and becomes the name of the control. A screen reader announces it as “link, [alt text]” or “button, [alt text]”. If the alt is missing or describes the picture instead of the purpose, the user can’t tell what activating it will do.

This is one of the most common accessibility failures on the web. In WebAIM’s 2026 analysis of one million home pages, 45% of the images missing alt text were linked images, “resulting in links that were not descriptive”, and one in four linked images had no alt text at all (WebAIM Million 2026). The same report lists “empty links” on 46.3% of home pages and “empty buttons” on 30.6%.

The rule: describe the action or destination

W3C’s guidance on functional images is direct: “The text alternative for the image should convey the action that will be initiated (the purpose of the image), rather than a description of the image.” Its examples: “print this page” rather than “(image of a) printer”, “search” rather than “magnifying lens”, and “Example.com homepage” rather than “Example.com logo” (W3C, Functional Images).

That lines up with two WCAG requirements:

• 1.1.1 Non-text Content: if non-text content is a control, “it has a name that describes its purpose” (W3C).
• 2.4.4 Link Purpose (In Context): the purpose of each link should be clear from its text or its context.

Five situations and what to do

1. The image is the only thing in the link

<a href="/"><img src="logo.svg" alt="Northwind Coffee home"></a>

The alt must carry the whole link name. Say where the link goes. Don’t say “click here” or “link to”. The screen reader already says “link”.

Missing or empty alt here is a failure. With alt="" and no other text, the link has no accessible name, and W3C notes that screen readers will typically fall back to “the image file name, the image URL, or the URL for the link destination” (W3C).

2. The image and text are in the same link

<a href="/guides/roasting/">
  <img src="beans.jpg" alt="">
  How we roast our beans
</a>

The link text already names the destination, so the image is decorative within the link. Use alt="" so the link isn’t announced as “How we roast our beans How we roast our beans”. This is W3C’s “Logo image within link text” case and technique H2, “Combining adjacent image and text links for the same resource”.

A very common pattern this fixes is card grids where the thumbnail and the title are separate links to the same article. Better still, wrap both in one link, or make the image a non-link with alt="".

3. The image adds information to the link text

<a href="/report.pdf">
  Annual report 2026 <img src="pdf-icon.svg" alt="(PDF)">
</a>

If an icon tells the user something the text doesn’t, such as file type or “opens in a new window”, put that in the alt. W3C’s example uses alt="new window" for a new-window icon.

4. Icon-only buttons

<button type="submit"><img src="search.svg" alt="Search"></button>

Use the verb or action: “Search”, “Close”, “Open menu”, “Add to basket”, “Next slide”. For <input type="image"> (the old image-as-submit-button), the alt attribute is required and should say what the button does (technique H36, listed on W3C’s functional images page).

If the icon is an inline SVG or an icon font rather than an <img>, there’s no alt attribute. Hide the graphic with aria-hidden="true" and name the button another way:

<button aria-label="Close dialog">
  <svg aria-hidden="true" focusable="false">…</svg>
</button>

5. Social media and app-store badges

<a href="https://instagram.com/northwind">
  <img src="ig.svg" alt="Northwind Coffee on Instagram">
</a>
<a href="https://apps.apple.com/...">
  <img src="app-store-badge.svg" alt="Download on the App Store">
</a>

“Instagram” alone is acceptable. Adding the brand makes it unambiguous when users list all links on a page out of context, which screen reader users often do.

Before and after

Don’t forget “Label in Name”

WCAG 2.5.3 Label in Name asks that when a control has visible text, its accessible name includes that text. It matters for voice control users who say “click Subscribe”. If a button shows the word “Subscribe” as part of an image, don’t name it “Join our newsletter”. Start the name with the visible word, for example “Subscribe to our newsletter”.

Getting it right at scale

The hard part is finding these images. A linked image looks the same as any other image in your CMS, but it needs different alt text. Things that help:

• Fix templates, not pages. Header logos, social icons, cart buttons and card components appear on every page. Fixing the template fixes thousands of instances at once.
• Watch for “same alt on every card”. CMSs often fill linked thumbnails with the post title. If the title is also linked text right next to it, switch the thumbnail to alt="".
• Test with a screen reader’s links list. VoiceOver (rotor) and NVDA (Insert+F7) can list every link on a page. If you hear “logo, logo, image, link, link”, you’ve found your problem.

How Altpass treats linked images

Altpass checks whether each image is inside a link or button and, if it is, looks at the link’s destination and any other text inside it. When it drafts alt text for a linked image, it writes for the destination or action (“Northwind Coffee home”, “Next slide”) rather than describing the graphic. When the link already has text, it suggests alt="". The free checker flags linked images with missing or empty alt as high priority, because they create links with no name.

You still review every suggestion. “Where does this link go?” is usually easy for a person to answer and easy for a tool to guess wrong.

Check your pages

Run the free Altpass checker on your homepage. Header and footer issues show up straight away, and fixing them in the template usually clears dozens of issues across the site in one go.

Updated 2026-10-07