Link

Links are essential for navigation but can be frustrating if not properly considered.

Screen readers expect links and buttons to behave differently. Misusing them can be disorienting. Screen reader users often navigate via link lists, so avoid vague labels like "read more" or "click here."

Use this component only for links that navigate to another location, page, or downloadable file. For in-page actions (e.g., opening modals, expanding widgets, submitting forms), use specific components like buttons.

Accessibility and usability expectations

Presentation

Cognition

• A link’s purpose must be obvious from the link text alone. If you can't get an idea of where a link will take you based on the link text without reading the surrounding text, the link text should be updated
• Ensure a link's purpose can be understood from the link text alone, without needing the surrounding context

Vision

• Color alone shouldn't distinguish links from text, as this can be hard for users with low or color blind vision
• Keep underline styling on links within body text for easy identification
• Like normal text, a link must have a 4.5:1 contrast against the background color it’s placed on
• If a link is surrounded by text, it must be underlined or pass a 3:1 contrast against the surrounding text
• Visual cues to demarcate links include:
  • The accent.fg color with fg.default text on canvas[...] backgrounds
  • Underlining the link text
  • Using an icon before or after the link
  • Using a background shape behind the link
  • A link color with 3:1 contrast against surrounding text and 4.5:1 against the background
• Links should look like links, not buttons, except in rare circumstances like CTAs
• Avoid underlining every link (e.g. navigation lists), but ensure it's visually clear that the element is a link

Mobility

• Links must have a minimum target size of 24 × 24 CSS pixels to ensure they are easily activated by users with limited dexterity or who are using touch devices

Adaptability

• Links and surrounding content must remain readable and operable when the page is zoomed to 400% or when the viewport is resized to 320px wide. Links should reflow naturally without causing horizontal scrolling
• Links must not break layout or overlap with other content when users increase text size up to 200% using browser controls
• Ensure links remain legible and don't break layout when users apply custom text spacing

Interaction

Keyboard

• Ensure links receive our global focus indicator styling when navigating with a keyboard (reference: Focus management)

Engineering for AT Compatibility

Screen reader

• Screen readers expect links and buttons to behave differently. Misusing them can be disorienting
• Screen reader users often navigate via link lists, so avoid vague labels like "read more" or "click here"
• Links must have appropriate link text that is sufficiently descriptive, giving users enough information to understand where the link will take them
• For links wrapped around images, the image must have an appropriate text alternative, which acts as the link text
• When the muted property is used, the visual styling changes but not the programmatic accessibility. Don’t rely solely on it to distinguish links
• It may be acceptable in some scenarios to provide more descriptive link text to screen reader users via aria-label, but:
  • The visible text must be included in full in the accessible name
  • The sentence must be grammatically correct when read with both visible and ARIA labels
  • Prefer unified visible and accessible text when possible

Speech recognition

• The visible text of a link should also be part of the accessible name to ensure compatibility with voice activation tools

How to test links

Integration tests

• Activating a link changes the URL. It is not intended to be used as a trigger for an action. A button is more appropriate for elements that trigger an action when activated.
• Where muted links are used, this visual presentation is not used as the only way to differentiate links or to somehow convey semantic meaning
• The links have an appropriately descriptive link text; in the case of image links, the images have an appropriate text alternative

Component tests

• Links are rendered as standard <a href="…"> … </a> links
• Content passed into the component is output as the link's visible text

Implementation requirements

Setting the muted property changes the visual presentation of the link to use a more subdued color. However, this visual change is not conveyed programmatically – so muted links will be announced the same way as regular links by screen readers. Don't rely solely on the muted property to distinguish links that serve a different purpose. If links need to be differentiated, make the difference clear in the link text itself. Alternatively, group these links separately and add context, such as a preceding heading or explanatory paragraph.

Links must have appropriate link text that is sufficiently descriptive – giving users enough information to understand where the link will take them. For links that are wrapped around images, make sure that the images have an appropriate text alternative, as this will act as the link text.

Functionality and purpose

A link's function is to navigate to a different page or new content. If instead a feature on the page is activated, use a <button>. Learn when to use a link or button.

A link's purpose must be obvious from the link text alone. If you can't get an idea of where a link will take you based on the link text without reading the surrounding text, the link text should be updated. Learn how to write good link text.

This is important because screen readers allow users to browse through a list of links, where the link text is the only clue of where a link will take you.

Visual distinction & contrast

Like normal text, a link must have a 4.5:1 contrast against the background color that it is placed on. Use a contrast checker to validate that your link meets this required contrast.

If a link is surrounded by text, it must be underlined or pass a 3:1 contrast against the surrounding text as well. Alternatively an icon, a background shape or an outline can demarcate a link.

Some examples of this are:

• links within body text
• a headline and subline which both are individual links
• issue numbers or usernames within a commit line

Guidelines

• Visually demarcate your links by using:
  • the accent.fg color in combination with fg.default for the surrounding text on any of the canvas.[...] colors
  • an underline for the link text
  • an icon before or after the link text
  • using a background shape behind the link
  • using a link color that has a 3:1 contrast against the surrounding text color AND a 4.5:1 against the background color
• Make sure a link's purpose can be understood from the link text alone, without needing the surrounding context.
• Links should look like links, not buttons, except in rare circumstances, like calls to action.

Do

Be descriptive with your links so that they can stand alone and be understood.

Don’t

Don't use generic terms like 'click here' that can't be understood out of context.

Do

Underline links in paragraphs and sentences

Don’t

Don't use underlines for non-link highlights or forget to demarcate links

Do

Use a link color that has a 3:1 contrast against the text color

Don’t

Don't use a color that has less than a 3:1 contrast against the text color for links

Do

Use an icon or a background shape to demarcate a link

Don’t

Don't use text styles like italic or bold to demarcate links

For engineers

• Use Primer link components:
  • Rails component
  • React component
• Don't override the link styling provided in the components
• Make sure links receive our global focus indicator styling when navigating the page with a keyboard (reference: Focus management)
• Don't use the title attribute
  • Content within a title is inaccessible for many users, such as touch-only and keyboard-only users. If additional content needs to be associated with a link consider using a Tooltip or alternatives to a tooltip.
• Avoid adding side effects to link click events. Links should navigate, not affect the page.
• Don't force links to open in a new tab/window by setting the target property.
• Links should always open in a new window when clicking while holding Command/Control.

Common mistakes

• Only adding an underline to a link when it has focus or is hovered over
• Underlining every link on the page. For example, a navigation list is a list of links but navigational links don't have to be underlined because the intent is understood and an underline is not needed to identify the interactive nature of the control.

Writing link text

Link text should be descriptive enough to convey the destination without relying on the surrounding text. Screen reader users often tab through links on a page to quickly find content without needing to listen to the full page. When link text is too generic like "Read more", the destination of the link is not conveyed.

It may be acceptable in some scenarios to provide a more descriptive link text for screen reader users by setting the aria-label. However, this technique will result in divergence between the label and the text and is not an ideal, future-proof solution. Whenever possible, prefer a single descriptive link text that is available for both sighted users and screen reader users.

If you must resort to the ARIA technique to provide a descriptive link text, follow these principles:

1. The visible text is included in full as part of the accessible name to avoid a violation of SC 2.5.3: Label in Name.
2. The sentence that the link is a part of is well-formed and grammatical when read with both the visible text and the accessible name.

  There are various plans available.
  <a href="..." aria-label="Learn more about GitHub pricing plans">Learn more</a>

  <a href="..." aria-label="Learn more about keyboard shortcuts">Keyboard shortcuts</a> allow you to access common commands more quickly.

As demonstrated in the examples, this technique adds more complexity to the code and can introduce more problems than it solves so only use this technique if absolutely necessary.

Additional resources

• Color to Distinguish Links from Text (requires a subscription to access the content)
• Accessibility Insights plugin: With the Accessibility Insights plugin installed, open the plugin, visit the Assessment option and select 7. Links
• WebAIM: Links and Hypertext - Introduction to Links and Hypertext
• erblint-github: Avoid generic link text

Related WCAG guidelines and success criteria

• Understanding Success Criterion 4.1.2: Name, Role, Value
• Authoring Practices Guide - Links
• Accessible Rich Internet Applications (WAI-ARIA) 1.2 (w3.org)
• Understanding Success Criterion 2.4.4: Link Purpose (In Context)