Link text and the ADA

Links heard out of context

Screen reader users often pull up a list of all links on a page. In that list, "Agenda", "Read more" and "Click here" repeat a dozen times and mean nothing. Voice control users who say "click Agenda" face the same ambiguity.

Success Criterion 2.4.4 says the purpose of each link can be determined from the link text alone, or from the link text together with its programmatically determined link context. In HTML, context includes the text in the same sentence, paragraph, list item or table cell, and the associated table header cell. Links whose purpose would be ambiguous to everyone, even people without disabilities, are excepted.

The simplest approach is link text that states the purpose. If you rely on context, place it in the same list item or paragraph, ideally before the link.

Typical offenders on city and school sites

• Meeting calendars with "Agenda" and "Minutes" links under a separate date heading.
• News and notices with "Read more".
• Bare URLs and file names used as link text.
• Cards where an image link and a title link go to the same place.
• Links that open a payment site in a new tab with no mention of it.

Residents rely on these links for deadlines and services, so ambiguous links are a barrier even before anything fails technically.

Keep the context with the link

Context counts when it is programmatically tied to the link, such as in the same list item. A heading or paragraph elsewhere does not.

<p>City Council, May 6</p>
<ul>
  <li><a href="/a/0506">Agenda</a></li>
  <li><a href="/m/0506">Minutes</a></li>
</ul>

<ul>
  <li>City Council, May 6:
      <a href="/a/0506">Agenda</a>,
      <a href="/m/0506">Minutes</a></li>
</ul>

Bare URLs and file links

Say what the link is and, for files, its type and size. Mentioning that a link opens in a new tab is good practice, though not part of this criterion.

<a href="/files/PRR-2024-final-v3.pdf">
  https://example.gov/files/PRR-2024-final-v3.pdf
</a>

<a href="/files/PRR-2024-final-v3.pdf">
  Public records request form (PDF, 180 KB)
</a>

One clear link per card

An image link with empty alt text next to a text link with the same destination leaves a link with no name. Wrap the card in one link, or make the text link the only one.

<a href="/events/farmers-market"><img src="fm.jpg" alt=""></a>
<a href="/events/farmers-market">Farmers market</a>

<a href="/events/farmers-market">
  <img src="fm.jpg" alt="">
  <h3>Farmers market, Saturdays 8 AM to noon</h3>
</a>

Links in mobile apps

Native links need meaningful text too. LinkAnnotation and withLink need Compose UI and Foundation 1.7 or later. SwiftUI:

Link("Click here",
     destination: URL(string: "https://city.example/appeals")!)

Link("Parking ticket appeals",
     destination: URL(string: "https://city.example/appeals")!)

Jetpack Compose:

ClickableText(
    text = AnnotatedString("Click here"),
    onClick = { openAppeals() }
)

Text(buildAnnotatedString {
    withLink(LinkAnnotation.Url("https://city.example/appeals")) {
        append("Parking ticket appeals")
    }
})

Verifying the fix

1. Use a screen reader's links list (or a browser extension that lists links). Read each one aloud. Can you tell where it goes?
2. Look for duplicates: links with the same text that go to different places. Different text for the same place is advisory only.
3. For links that rely on context, check that the context is in the same sentence, list item or table cell.
4. Test with voice control: say the visible text of a few links. Does the right one activate?

Automated tools find empty links and some generic text such as "click here", but they cannot judge every ambiguous label.

Mistakes and a ship-it list

• Adding aria-label text that does not contain the visible words.
• Putting the context in a heading far from the link.
• Using the same text for links that go to different documents.
• Image-only links without an accessible name.

Ship it when every link makes sense from its own text or its context in the same sentence, list item or cell, and identical text always goes to the same place.

See first steps for where to begin a review.

Sources

• Understanding SC 2.4.4: Link Purpose (In Context) (W3C), opens in a new tab
• 28 CFR Part 35, Subpart H: Accessibility of Web Information and Services (eCFR), opens in a new tab

Standard version: WCAG 2.1 (W3C Recommendation, 5 June 2018), as named in the Title II web rule. This page is for informational purposes only and is not legal advice. For binding requirements, refer to the official ADA statute and regulations, and ask a lawyer how they apply to you.