AccessLint Rule: Links must have discernible text via content, aria-label, or aria-labelledby.

About this AccessLint rule

Every link on a page needs an accessible name that screen readers can announce. When a link has no discernible text, screen reader users hear something like "link" with no indication of where the link goes or what it does. They are left guessing, which makes navigation difficult or impossible. Keyboard-only users who tab through links also rely on announced link names to understand the page structure.

This rule checks that every element with a link role (including <a> and <area> elements with an href attribute) that is included in the accessibility tree has a non-empty accessible name. The accessible name can come from the element's text content, an aria-label attribute, an aria-labelledby attribute, or (for image links) the alt attribute on the contained image.

Why this matters

WCAG Success Criterion 2.4.4 (Link Purpose - In Context) requires that the purpose of each link can be determined from the link text alone or from the link text together with its surrounding context. Success Criterion 4.1.2 (Name, Role, Value) requires that all user interface components have a name that can be programmatically determined. Both are Level A requirements, meaning they are baseline expectations for any accessible website.

When a link has no accessible name, both of these success criteria fail. Screen reader users cannot distinguish one link from another, and they cannot decide whether to follow a link without knowing its destination.

How to fix it

The fix depends on what the link contains:

Text links — Put descriptive text inside the <a> element. The text should describe the link's destination or purpose. Avoid generic phrases like "click here" or "read more" because these are meaningless when read out of context, such as in a screen reader's list of links.

Image links — If the only content inside a link is an <img> element, provide alt text on the image that describes the link destination, not the image itself. For example, if a logo image links to the homepage, use alt="Homepage" rather than alt="Company logo".

Icon links — Links that contain only an SVG icon or icon font with no visible text need an aria-label on the <a> element, or the SVG itself needs a <title> element referenced appropriately.

aria-labelledby — If the accessible name comes from another element on the page, use aria-labelledby with the id of that element.

Empty or whitespace-only links — Remove them if they serve no purpose, or add appropriate text content.

Examples

Empty link (fails)

This link has no text content and no accessible name. A screen reader announces it as "link" with no further information.

<a href="https://example.com"></a>

Image link without alt text (fails)

The image inside the link has no alt attribute, so the link has no accessible name.

<a href="/">
  <img src="logo.png">
</a>

Link with generic text (avoid)

While this technically has an accessible name, "click here" is meaningless out of context. Screen reader users browsing a list of links will see multiple entries that all say "click here."

<p>To learn about our services, <a href="/services">click here</a>.</p>

Text link (passes)

The link text clearly describes the destination.

<a href="https://www.w3.org/WAI">Web Accessibility Initiative (WAI)</a>

Image link with alt text (passes)

The alt attribute describes the link destination, giving the link a clear accessible name.

<a href="/">
  <img src="logo.png" alt="Homepage">
</a>

Icon link with `aria-label` (passes)

The aria-label provides the accessible name for a link that contains only an icon.

<a href="/search" aria-label="Search">
  <svg aria-hidden="true" focusable="false">
    <use href="#icon-search"></use>
  </svg>
</a>

Link with `aria-labelledby` (passes)

The link gets its accessible name from a heading elsewhere on the page.

<h2 id="news-heading">Latest news</h2>
<a href="/news" aria-labelledby="news-heading">
  <img src="news-thumbnail.jpg" alt="">
</a>

In this example, the image has an empty alt because the aria-labelledby attribute already provides the link's accessible name. The screen reader announces "Latest news, link."