# Links must have discernible text via content, aria-label, or aria-labelledby.

> Canonical HTML version: https://rocketvalidator.com/accessibility-validation/accesslint/0.16/navigable/link-name
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

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.

```html
<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.

```html
<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."

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

### Text link (passes)

The link text clearly describes the destination.

```html
<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.

```html
<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.

```html
<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.

```html
<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."