How to fix “Links must have discernible text”

Screenshot of website footer area that has social media icons within focus

If you’re using axe DevTools or other accessibility scanning tools and see the “Links must have discernible text” message, you may be wondering how to address this. This article is meant to show how to fix “Links must have discernible text” message.

What does ‘discernible text’ even mean?

It means that a screen reader, or even a search crawler, can’t see any text here. I often see this on pages that use logos for links to social media.

Example

For example: here is some basic HTML showing a link to a twitter account:

<a href="https://twitter.com/walmart">
  Follow us on Twitter
</a>

In the above example, a machine can read over that HTML and determine “this is a link”, as well as determine where the link is going, and also what the link says.

But what if someone chooses to use an image of a Twitter logo instead of the text above:

<a href="https://twitter.com/walmart">
  <img src="twitter-logo.png" />
</a>

In the above HTML, a machine can read of that HTML and determine “this is a link”, as well as determine where the links is going, but there is no text of what this link is supposed to say. There is no discernible text. It might as well look like this:

<a href="https://twitter.com/walmart"></a>

Just blank!

One way to fix this, when using an img tag especially, is to include an alt attribute:

<a href="https://twitter.com/walmart">
  <img src="twitter-logo.png" alt="Follow us on Twitter" />
</a>

With above example, while a machine scanning this code may not be able to tell what the twitter-logo.png looks like, it can see the alt value! So adding an alt attribute with an appropriate value could be one way to resolve this issue.

What about Font Awesome?

Many sites use a font logo system, like Font Awesome, to display social links:

<a href="https://twitter.com/walmart">
  <i class="fa-brands fa-twitter"></i>
</a>

In this instance, there is no img tag above, therefore the alt attribute doesn’t apply. What can one do here? One method is to use aria-label, like so:

<a href="https://twitter.com/walmart" aria-label="Follow us on Twitter">
  <i class="fa-brands fa-twitter"></i>
</a>

In the above example, an aria-label attribute is added to the link, and machine screen readers know how to interpret that value.

Title

While not suggested, another alternative is the use of the title attribute instead of aria-label:

<a href="https://twitter.com/walmart" title="Follow us on Twitter">
  <i class="fa-brands fa-twitter"></i>
</a>

Use of title is also picked up by screen readers. Not only that, people who use a mouse can mouse over this link, and a common browser behavior is to display the title text as a tooltip after half a second of mouse hover.

Aside: so what’s the problem with title?

While this makes the “Links must have discernible text” message go away, it’s not a recommended practice. Historically, some browsers have latched onto the tooltip hover effect of title. The problem is that not all browsers implemented this consistently, nor do screen readers have a consistent way of supporting access to the title attribute. Additionally, the tooltip cannot work on mobile/touchscreens, and therefore authors should likely avoid this because of the inconsistency it provides to end users.

So while it gets rid of that message, it doesn’t necessarily make my site more usable.

Text just for Screen Readers

Another tool, other than applying attributes to the link, is to insert text and styling it in a way that it doesn’t show up to sighted users, but it still accessible by screen readers. Take the example below:

<a href="https://twitter.com/walmart">
  <i class="fa-brands fa-twitter"></i>
  <span class="sr-only">Follow us on Twitter"</span>
</a>

Note the span with the class of sr-only – by itself this class doesn’t do anything special. If you don’t add any styles associate with that class name, then the text ‘Follow us on Twitter’ will just show up. But if you include the following snippet in your stylesheet, it will disappear from sight, while still being available to screen readers:

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0,0,0,0);
  white-space: nowrap;
  border-width: 0;
}

Does that look more complicated than display:none? Why not use display: none? The answer is that screen readers will also ignore text that is styled to display: none, so best to avoid it if you want screen readers to pick up on the text.

Or just show the text to everyone!

Another method that is worth mentioning is to just show the text to all users – not hide it. Not everyone has memorized what these logos represent. Maybe having text alongside the logo available for everyone to see will make the area more usable. The less a user has to think about what an action will do, the more usable a site will feel.

<a href="https://twitter.com/walmart">
  <i class="fa-brands fa-twitter"></i>
  Follow us on Twitter
</a>

So running scans again after the above adjustments should address the ‘Links must have discernible text’ – at least for those instances.

In summary

I hope that helps give some insight into how to solve for “Links must have discernible text”. The above techniques are what I’ve used, and the common areas where I’ve seen this sort of thing.

The Mastodon post for this article is a good place for thoughts, questions, comments, or corrections. I’m still learning, and I welcome feedback.

Updated 2023-02-09: Incorporating feedback from Dan Keck .

Related Posts