Skip to main content
An official website of the United States government

Link

Links are interactive elements that allow users to navigate to another location— a different page, website, or section within the same page.

View in Figma

Usage

Where to use

  • Links can be used on their own or within text to provide more context for the user journey.

When to use

  • To add a call-to-action or lead users to find more information.

When to consider something else

  • Use a Button to identify important actions users should take on your website, such as Download, Apply, Learn more, etc.

Best Practices

  • Do not overuse links within text. Using too many links can make it difficult for users to identify their next steps.
  • Be descriptive to explain a link’s purpose, helping users to understand a link’s destination.
  • Encode email and phone links.
  • Clearly identify external links when a link takes a user outside of the website.
    • Note: Do not use an external link indicator when linking to another federal government (.gov) website.

External Links

  • When a link navigates outside of the website or to a non-government website, it must display an external icon after it.
    • Use the global settings to set internal links and bypass default settings, if needed.

Global External Link Settings

  • To display the external link icon the global theme variable must be used: $theme-set-automatic-external-links-on.

    (Default) Display external icon for all usa-links: $theme-set-automatic-external-links-on: true !default;

    Disable the external link icon: $theme-set-automatic-external-links-on: false;

  • To set specific links (e.g. links to government websites) as internal, the following variable must be used: $theme-internal-domains.

    Default setting:

    $theme-internal-domains: ( ".gov", "mailto:", "javascript:", "public.govdelivery.com", "www.gov.uk" ) !default;

Accessibility

  • Include text within the link that is descriptive and indicates where a link is going.
    • For example, do not only link the words "click here" or "here."
    • Instead use this text to share the title of the page the links goes to or indicate what action the user will take when clicking the link.
  • Allow keyboard navigation of links.
    • Use should be able to navigate between links by using the “Tab” key and activate a link by pressing the “Enter” key.
  • Allow users to activate link hover and focus states when using a mouse and keyboard.

Code Snippets

If the global external link default settings are set using the domain variables provided, an external icon should display appropriately when using the usa-link class. However, there are also options to manually force an external link icon to display or to hide the icon, regardless of whether the link is internal or external.

  • Force the external link icon to display: Add class usa-link--external in addition to usa-link.

  • Hide the external link icon: Add the data property data-ncids-internal-link to the anchor element that has the class usa-link.

Component Preview
<div>
  <a href="https://www.google.com" class="usa-link">External Link Example</a><br/>
  <a href="https://www.cancer.gov" class="usa-link usa-link--external">Internal Link Icon Override (Show)</a><br/>
  <a href="https://www.google.com" class="usa-link" data-ncids-internal-link>External Link Icon Override (Hide)</a>
</div>

Packages

Import this Sass partial into your style sheet.

@forward "usa-link";