Skip to content



Links are user interface elements that navigate you to a new place or new content. Contrast this with buttons, which are designed to activate a feature.


Links can do things like help with page context, reference similar items of interest, and allow for endless connected information surfing through sites like Wikipedia. Links play a key part in your experience on the web, but without proper consideration they can be frustrating to use, skipped over, or completely unnoticed.

For screen reader assistive technology, links and buttons are expected to function differently from each other. If a link is activated and does not do what was expected, that can be disorienting and frustrating.

A common way a screen reader might navigate the page is by going through a list of all the links on the page. Without context, "read more" or "click here" links are not helpful.

People who have low or colorblind vision may have trouble identifying links that just use color to distinguish them from plain text, this is why keeping the underline styling on links within body text is important for identification.

  • Check a link's function. If clicking a link activates a feature on the page, it should be a <button>, and vice versa.
  • Check a link's purpose. If you can't get an idea of where a link will take you based on the link text alone, the link text should be updated. Learn how to write good link text.
  • Check a link's contrast. Because links are text-based, they need to pass 4.5:1 against the background color that they are on.
  • In body text, like a Markdown file, check to make sure that all links have underline styling.


For designers

  • Make sure you use the correct accent color for links in your designs. Double check the color you're using if you're using it on anything other than a white background. For more context on color, check out our color documentation.
  • Make sure a link's purpose can be understood on its own without the surrounding context in concise words.
  • Links should always be underlined if they're in body text.
  • Links should look like links, not buttons, except in rare circumstances, like calls to action. If the action takes you somewhere rather than doing something on the page, it should be semantically coded as a link regardless of the visual style.
Markdown paragraph with descriptive links

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

Markdown paragraph with links like 'Click here' and 'find out more'

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

Underlined username link in issue subheadingUnderlined community guidelines link in text under a markdown comment text area.

Underline links in paragraphs and sentences

Issue subheader with none of the links underlinedGitHub commnuity guideline link not underlined in sentence.

Don't forget to underline links in paragraphs and sentences

For engineers

  • Use Primer link components:
  • 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.

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.

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.

Accessible name fully includes the visible link text, "Learn more" and is well-formed with either label.

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


Accessible name results in poorly-formed sentence, "Learn more about keyboard shortcuts allow you to access common commands more quickly".

<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