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>Guidance
Overview
Each item below is explained in the guidance sections that follow.
What you should do
What you shouldn't do
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. Settingnoreferreron 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:
-
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:andtel: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:andtel:. 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.
Accessibility guidance
- 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.
Using the link component
Link settings
| 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. |
Link variants
| Variant | Description |
|---|---|
|
|
Display an external link icon after the link. |
Additional information
- OMB M-23-22: Delivering a Digital-First Public Experience
- OMB M-10-23: Guidance for Agency Use of Third-Party Websites and Applications [PDF, 9 pages]
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.
| Total tests |
Passed
|
Passed with exceptions
|
Conditional
|
Failed
|
|---|---|---|---|---|
| 4 | 3 | 0 | 1 | 0 |
Overview of recent accessibility test results:
Learn more on the link accessibility tests page.
Package
-
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 | Description |
|---|---|---|---|
| 2024-01-17 | N/A |
|
Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2138 |
| 2023-11-20 | N/A |
|
Added |
| 2023-11-20 | N/A |
|
Updated code examples for encoding email and phone links. More information: uswds-site#2162 |
| 2023-06-09 | 3.5.0 |
|
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 |
|
External link icons and link text now wrap as expected. More information: uswds#5046 |
| 2022-04-28 | 3.0.0 |
|
Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656 |
| 2022-01-20 | 2.13.1 |
|
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 |
|
Updated component definition and use case. More information: uswds-site#1275 |
| 2021-11-01 | 2.12.2 |
|
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 |
|
Added a link to the external link indicator research findings. More information: uswds-site#1261 |
| 2021-08-18 | 2.12.1 |
|
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 |
|
Updated external link guidance and added a summary of external link indicator research findings. More information: uswds-site#1249 |
| 2021-06-16 | N/A |
|
Updated accessibility and usability guidance for external links. More information: uswds-site#1225 |
| 2021-03-18 | N/A |
|
Added documentation for the |
| 2021-03-17 | 2.11.0 |
|
Updated and improved guidance around links. More information: uswds-site#1180 |
