Links need a name

Rule: axe/link-name
Checks: Links must have discernible text
WCAG: 2.4.4, 4.1.2
Fix class: content: A fix needs authored text.

Who it affects

People who use a screen reader or a braille display, most of them blind.
People who control the page by speaking.

How to fix it

The link shows only an icon or a CSS background image

Name the link for where it goes, with visually hidden text inside it or with aria-label, and hide the icon from assistive technology with aria-hidden="true".

<a href="/account">
  <svg aria-hidden="true" focusable="false"><use href="#icon-user"></use></svg>
  <span class="visually-hidden">Your account</span>
</a>

The link holds only an image with no `alt`, or an empty one

Give the image an alt that says where the link goes. For a logo that links to the home page, use the organization’s name and “home”.

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

An empty link is stretched over a card or other content

Wrap the link around the card’s heading text instead, and stretch its clickable area over the card with CSS. The heading then names the link.

<article class="card">
  <h2><a href="/recipes/lentil-soup" class="card-link">Lentil soup</a></h2>
  <p>A one-pot soup ready in 30 minutes.</p>
</article>

The link runs script rather than going somewhere, such as `href="#"`

Make it a <button type="button"> and name it for its action. People expect a link to take them somewhere and a button to do something.

Fixes that fail

Adding only a `title` attribute

axe accepts it and screen readers announce it, but it appears only on mouse hover, so keyboard, touch and voice control users never see a name.

Naming the link “Link” or “Click here”

Screen readers already announce a link as a link, and neither name says where it goes, which is what people scanning a list of links need.

Adding `aria-hidden="true"` to the link

It takes the link out of the rule, but the link stays focusable, so keyboard and screen reader users reach a link nothing announces. axe then reports it under aria-hidden-focus.

In React

The part of the fix that differs in React, in its syntax. The rest of the guidance holds.

An icon link component does not pass a name to the `<a>` it renders

Take the name as a required prop and render it as visually hidden text inside the link, or spread the remaining props onto the router’s Link or the <a>, so an aria-label from the caller reaches it.

function IconLink({ href, icon: Icon, label }) {
  return (
    <a href={href}>
      <Icon aria-hidden="true" focusable="false" />
      <span className="visually-hidden">{label}</span>
    </a>
  );
}

Fixes that fail in React

Passing `aria-label` to a link component that does not forward it

The prop never reaches the DOM, so the link stays unnamed. Check the rendered HTML, not the JSX.

More on the rule

axe-core’s documentation of the rule

CORA’s fix guidance adapts content from accessibility-agents, under the MIT License: see its notice.