Components

Link

A link connects users to a different page or further information.

Passed WCAG 2.1 AA

About the link component

Links are navigational elements that direct visitors to other locations, either on the same page or to a different page or site. They can be inline or separate from the text flow. Since every link is a potential user interaction, too many links can be overwhelming. Be judicious with links to better identify necessary calls to action.

This is a text link on a light background.

This is a visited link.

This is a link that opens in the current tab and goes to an external website.

This is a link that opens in a new tab and goes to an external website.

This is a text link on a dark background.

This is an alternate external text link on a dark background. 

<p>
  This is <a class="usa-link" href="javascript:void(0);">a text link</a> on a
  light background.
</p>
<p>
  This is
  <a class="usa-link usa-color-text-visited" href="javascript:void(0);"
    >a visited link</a
  >.
</p>
<p>
  This is a link that opens in the <em>current</em> tab and goes to an
  <a
    class="usa-link usa-link--external"
    rel="noreferrer"
    href="https://i.giphy.com/media/WPzQF6ruiIIVzHNlwX/source.gif"
    >external website</a
  >.
</p>
<p>
  This is a link that opens in a <em>new</em> tab and goes to an
  <a
    class="usa-link usa-link--external"
    rel="noreferrer"
    target="_blank"
    href="https://i.giphy.com/media/WPzQF6ruiIIVzHNlwX/source.gif"
    >external website</a
  >.
</p>
<div class="usa-dark-background padding-1 display-inline-block">
  <p>
    This is
    <a class="usa-link" href="javascript:void(0);"
      >a text link on a dark background</a
    >.
  </p>
  <p>
    <a
      class="usa-link usa-link--alt usa-link--external"
      rel="noreferrer"
      href="https://i.giphy.com/media/WPzQF6ruiIIVzHNlwX/source.gif"
      >This</a
    >
    is an alternate external text link on a dark background.
  </p>
</div>

Overview

Each item below is explained in the guidance sections that follow.

What you should do

  • Clearly identify external links
  • Notify users about non-federal external links
  • Use unique, meaningful link text
  • Simplify link placement in body text
  • Link directly to the most relevant page
  • Indicate nonpublic links that require authentication
  • If you use an external link indicator, use it consistently for all text links
  • Add rel="noreferrer" to external links
  • Provide text context for external links
  • Add a non-endorsement statement
  • Indicate file type and size for links to non-HTML content
  • Identify jump links in body text
  • Write out email and phone links
  • Encode email and phone links
  • Check with your IT security department regarding email link best practices

What you shouldn't do

  • Don’t rely only on color to distinguish links
  • Don’t block external links with disruptive notifications
  • Don’t use generic link text like “read more” or “link”
  • Don’t use the same link text for different URLs on the same page

What you should do

  • Clearly identify external links. The external link icon () is a good way to communicate that a link is external.

  • Notify users about non-federal links. Review this resource on Digital.gov for guidance on non-federal link requirements.

  • Use unique, meaningful link text. Link text should explain the link’s purpose and help the user understand the link’s destination. Vague and repetitive text like “click here” or “read more” is unhelpful to those using screen-reading software. Screen-reading software collects all page links into a single list, and users typically start with that list. When they do so, they will not be able to tell the difference between links with similar wording.

  • Simplify link placement in body text. A link requires mental effort, which affects readability. Reduce the number of links in a single sentence to simplify its message. Consider placing links at the beginning or end of sentences to improve readability.

  • Link directly to the most relevant page. Avoid links to pages that require further user action to locate the intended information.

  • Indicate nonpublic links that require authentication. Use text or an indicator like a lock icon to signal any link that is not available publicly. This includes links behind a login or other authentication like a paywall.

    Example 1:

    We’ve documented our research in the raw research notes 🔒.

    Example 2:

    We’ve documented our research in the raw research notes (requires login).

  • If you use an external link indicator, use it consistently for all external text links. If your project uses an external link indicator (like an icon), use that indicator for all text links across your site. If users learn to associate an external link with the indicator, they will also appropriately expect that text links without an indicator are not external links. Icon- or image-only links like social share buttons or logos do not need the same treatment as text links.

  • Use rel="noreferrer" property on external links. Setting noreferrer on links prevents the browser from leaking information about the original web address.

  • Provide text context for external links. Following a link is a user decision. Users need enough information to make that decision - short links without context often don’t provide that. Plain, straightforward text can be the best way to communicate to users that a link will take them away from your site, which can be useful whether the external link is to either a government or a non-government site. When possible, use the content of the link text itself to indicate where it goes. By itself, an external link indicator (like an icon) can be ambiguous. Adding plain text can help make any link destination more clear.

    Example 1:

    CDC recommends using sunscreen when you’re outside to reduce your risk of skin damage and skin cancer.

    To ensure food safety during an emergency, the Red Cross recommends you do not open the refrigerator or freezer.

    Example 2:

    Sun safety guidance [cdc.gov].

    Food safety during an emergency [redcross.org]

  • Add a non-endorsement statement to your site. Your “Policy and Notices” page should explain to users that your agency does not endorse the information on any linked non-federal site. See, for example, USA.gov’s linking policy. In addition to this site-level notice, consider adding additional non-endorsement statements on individual pages with non-federal links.

  • Indicate file type and size for links to non-HTML content. Whenever possible, create HTML pages instead of linking to files like PDFs. If you do link to a file, tell users ahead of time if the link may trigger a file download, and show the size and format of that file.

    We recommend including this information at the end of the link, in the format [FILE_TYPE, SIZE]. We recommend using the file type rather than a product name. Use uppercase for the file type and a comma for the separator. For file size, use the number of pages in the document or the size in MB or KB if the document is not paginated.

    Example 1:

    GSA published a report, Transforming the American Digital Experience [PDF, 18 pages]

    Example 2:

    Download the Revised 508 Standards Applicability Checklist [DOCX, 2 pages]

    Example 3:

    Download the USWDS 2.11.2 Design Kit for Sketch [ZIP, 13.3 MB]

  • Identify jump links in body text. Jump links (or in-page links) send the user to another part of the same page. This behavior can be unexpected in body text links. In these cases, use the link text like “jump to”, “above” or “below” to tell users that the destination is elsewhere on the same page.

    Example 1:

    Jump to video resources for more information about how to boil water.

    Example 2:

    For more information on how to boil water, see video resources, below.

  • Write out email and phone links. For mailto: and tel: links, write out email addresses and phone numbers so users can read or copy this information without selecting the link.

    Example:

    Email us at uswds@gsa.gov

  • Encode email and phone links. Some browsers don’t automatically display a clickable link for email addresses or phone numbers, so encode email and phone links with mailto: and tel:. Be sure to include the country code in phone numbers to support international users.

    Examples:

    <a href="mailto:program-team@agency.gov">program-team@agency.gov</a>

    <a href="tel:1-800-555-1234">1-800-555-1234</a>

  • Check with your IT security department regarding email link best practices. While displaying email addresses and phone numbers provides a better experience for users, it can also increase spam for the email recipient. One approach is to use a group email address to protect individuals. Another benefit of that approach is the email will remain the same even as staff and organizational structures change. You can also consider using a contact form instead of showing email addresses.

What you shouldn't do

  • Don’t rely on only color to distinguish links. Site visitors should be able to distinguish text links from surrounding text. In most cases, include an underline or bottom border on text links, in addition to a consistent link color. Text links not distinguished with an underline need a contrast level of at least 3:1 with their surrounding text (the same as AA Large, or a USWDS magic number of 40) and should show an underline on hover.

  • Don’t block external links with disruptive notifications. Allow users to follow external links without taking a separate action to acknowledge leaving your site. Roadblock notices, such as modals and dialog boxes, result in a poor user experience. Instead, communicate about a link’s destination through descriptive link text and external link indicators. Use your site’s policy and notices page to provide important information about non-government sites without disrupting the user experience.

  • Don’t use generic link text. Vague text like “click here” and “read more” is confusing and repetitive, especially to people using screen readers. Link text should describe the destination and explain where users will go if they follow the link.

  • Don’t use the same link text for different URLs on the same page. Differentiate between links by using unique text for each.

Test the link in your own project.

USWDS tested the link component for accessibility. You should test your implementation, too.

Use link accessibility tests
  • Allow keyboard navigation of links. Users should be able to navigate between links by using the “Tab” key. They should be able to activate a link by pressing the “Enter” key.
  • Link hover state should be visible on focus. Users should be able to activate hover and focus states with both a mouse and a keyboard.
Variable Description
$theme-external-link-sr-label-tab-new

Screen reader label for external links that open in new tabs.
$theme-external-link-sr-label-tab-same

Screen reader label for external links that open in current tab.
Variant Description

.usa-link--external

Display an external link icon after the link.

Additional information

Research findings

  • Qualitative comparison A/B test of external link indicator: In May–June 2021, USWDS conducted research around using an external link indicator for text links to external websites. We first performed a landscape analysis of commonly used external link icons and designed an alternative variant of the external link indicator. Then, we conducted a qualitative comparison A/B usability test of our default external link icon and a newly designed “Exit” badge. Our findings:
    • Users understand a link’s destination when that destination is included in the link text or the context of the link.
    • Users are more likely to ignore link icons and badges than think about their meaning.
    • Users didn’t consistently understand either the external link icon nor an “Exit” badge.
    • Users expect an icon or badge alongside a link to be clickable.
    • If users have a specific goal to accomplish on a page, they won’t leave that page and follow a link elsewhere until they complete their task on the current page.
    • Links can be a distraction when users read blocks of text.
    • Long link text can be hard to read or understand.
    • Government-speak and acronyms make links more confusing.
    • Paragraphs with lots of links can be hard to read or understand.
    • Users expect to find reference links at the bottom of the page.
    • Users find agency name/branding in the top left corner of a web page critical for orientation.

    Read the complete Research findings on GitHub →

Accessibility test status

The USWDS team did 4 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
4 3 0 1 0

Overview of recent accessibility test results:

  • Passed: 3
  • Passed with exceptions: 0
  • Conditional: 1
  • Failed: 0

Learn more on the link accessibility tests page.

  • Package usage: @forward "usa-link";
  • Dependencies: uswds-fonts, usa-icon

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-01-17 N/A
  • Guidance
 No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2138

2023-11-20 N/A
  • Guidance
 No

Added uswds-fonts and usa-icon to list of dependencies. More information: uswds-site#2162

2023-11-20 N/A
  • Guidance
 No

Updated code examples for encoding email and phone links. More information: uswds-site#2162

2023-06-09 3.5.0
  • Accessibility
  • Settings
 No

Labeled external links for screen readers. Adds a label for screen readers that identifies external links and if they open in a new tab. More information: uswds#5166

2023-03-09 3.4.0
  • Styles
 No

External link icons and link text now wrap as expected. More information: uswds#5046

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656

2022-01-20 2.13.1
  • Styles
 No

Fixed external link icon display bug in Safari. Fixed a bug that resulted in colored bars on the top and bottom of external link icons in Safari. More information: uswds#4439

2021-10-01 N/A
  • Guidance
 No

Updated component definition and use case. More information: uswds-site#1275

2021-11-01 2.12.2
  • Assets
  • Styles
 No

Fixed external link icon color. Resolved an issue with visited links where the icon color may not match the color of the link. More information: uswds#4297

2021-09-16 N/A
  • Guidance
 No

Added a link to the external link indicator research findings. More information: uswds-site#1261

2021-08-18 2.12.1
  • Styles
 No

Improved external link icon display. Made external link icon bigger and better aligned with the link text. More information: uswds#4277

2021-07-30 N/A
  • Guidance
 No

Updated external link guidance and added a summary of external link indicator research findings. More information: uswds-site#1249

2021-06-16 N/A
  • Guidance
 No

Updated accessibility and usability guidance for external links. More information: uswds-site#1225

2021-03-18 N/A
  • Guidance
 No

Added documentation for the usa-link--external variant. More information: uswds-site#1186

2021-03-17 2.11.0
  • Guidance
 No

Updated and improved guidance around links. More information: uswds-site#1180