Components

Link

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

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 must do

  • Clearly identify external links.
  • Provide required notification for non-federal external links.

What you should do

  • 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.
  • Show 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 on color alone to distinguish links.
  • Don’t roadblock external links with a modal window or dialog box.
  • Don’t use generic link text.
  • Don’t use the same link text for different URLs on the same page.

What you must do

  • Clearly identify external links. OMB’s Policies for Federal Agency Public Websites and Digital Services [PDF, 1.2 MB] states that agencies “must clearly identify external links from their websites” and that they “should choose the best approach to identify external links to users in a way that minimizes the impact on the usability of their websites and digital services.”

  • Provide required notification for non-federal external links. OMB’s Policies for Federal Agency Public Websites and Digital Services [PDF, 1.2 MB] states that you “must clearly state that the content of external links to non-federal agency websites is not endorsed by the federal government.”

    This requirement has two aspects:

    • Notification: We recommend employing a clear, consistent, user-friendly approach for all external links whether government or non-government links (see What you should do, below).
    • Non-endorsement: We recommend adding language to a policy and notices page on your site to explain to users that the agency does not endorse the information on any linked non-federal site. See, for example, USA.gov’s linking policy.

    Check with your Federal Web Council representative [digital.gov] and General Counsel regarding agency requirements for this endorsement language and notification approach.

    11. Ensure Information Quality and Accuracy

    The Internet enables agencies to communicate information quickly and easily to a wide audience, which, while of great benefit to society, also increases the potential harm that can result from disseminating incorrect information. Taking this into account, information disseminated from Federal Government websites and digital services, or from third-party services on behalf of the Government, is expected to be authoritative and reliable.

    The Information Quality Act applies to all information disseminated from Federal websites, and in certain cases, to information published to third-party sites on behalf of the Government. OMB has published Information Quality Guidelines to help agencies meet this requirement.

    [...]

    E. Agencies must clearly identify external links from their websites, and to the extent practicable update or remove the links when the external information is no longer sufficiently accurate, relevant, timely, necessary or complete.

    1. Agency websites must clearly state that the content of external links to non-Federal Agency websites is not endorsed by the Federal Government and is not subject to Federal information quality, privacy, security, and related guidelines.
    2. Agencies should choose the best approach to identify external links to users in a way that minimizes the impact on the usability of their websites and digital services.
    View the full text of M-17-06 [PDF, 1.2 MB]

What you should do

  • 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 particularly unhelpful to those using screen-reading software. These users are more likely to focus on link text only. Screen-reading software has a feature to collect all page links into a single list. In these lists, links that aren’t unique aren’t differentiable.

  • Simplify link placement in body text. A link has cognitive weight and this 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 directly available on the public web. 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 text links. If your project uses an external link indicator (like an icon), use it for all text links across your site. If users learn to associate an external link with the indicator, they will also 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 decision. Terse links without context often don’t give users enough information to make that decision. Plain, straightforward text can be the best way to communicate to users that a link will take them away from your site. This is useful whether the external link is to a government or a non-government site. When possible, use the content of the link text itself to indicate its destination. In isolation, an external link indicator (like an icon) can be ambiguous. 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]

  • Show file type and size for links to non-HTML content. When 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:. 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 increase spam for the email recipient. One approach is to use a group email to protect individuals. The email address will remain the same even as staff and organizational structures change. Also consider using a contact form instead of showing email addresses.

What you shouldn't do

  • Don’t rely on color alone 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 roadblock external links with a modal window or dialog box. Allow users to follow external links without taking a separate action to acknowledge leaving your site. Roadblock notices result in a poor user experience and are redundant with both the link’s destination context (see Provide plain text context for external links, above) any external link indicator (see If you use an external link indicator, use it consistently, above), and your site’s policy and notices page (see Provide required notification for non-federal external links, above).

  • Don’t use generic link text. Vague text like “click here” and “read more” is confusing and repetitive, especially to 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.

  • 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 →

  • 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
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