Components

Link

Use: Deployed

A link is a navigation element that can appear alone, inline (embedded), or in a group with other links. A link can trigger a download, but in general links go to internal or external pages when clicked.

Examples

Usage

When to use a default link

Navigation between pages. Navigating to another page (internal or external).
Navigation within a page. Anchor, or jump, to a specific header and section on a page.
Trigger an appropriate supporting application. Make email addresses and phone numbers open the relevant app by clicking or tapping them.

When to use an Active link

Collections, such as Hub pages. Active links can be seen on Hub pages
Less prominent links. For links that need less prominence than an Action link and may appear in a collection, we recommend using an Active Link. Active Links have a hover behavior that includes a background color change and an animated right-facing chevron icon for more emphasis.

When to use a Back link

As a replacement for breadcrumb on:
- Conventional Multi-step Forms that also:
  - Have a minimal header and minimal footer
  - Follow the one thing per page pattern pattern
  - Use the H1 element to represent the headline for the current form page, rather than the step title in the step indicator
  - Include only a Continue button and do not have a Back button after the form
- Short Forms that has a small amount of short, concise steps. For example, the Pact Act Wizard.
- Non-Form Pages where the current page was accessed from a related page and does not have additional navigation. For example, an appointment details page.

When to use a Calendar link

Adding an event to a calendar. Use when the link adds an event to a digital calendar.

When to use a Channel link

YouTube channel. Use when linking to a YouTube channel.

When to use a Download link

Downloading files. Use for download links including but not limited to PDFs and Excel files.

When to use a Video link

YouTube Video. Use when linking directly to a YouTube video.

When to consider something else

Use buttons for actions. Use a Button when you want to make a state change or submit a form. Example actions include, but are not limited to, “Add”, “Close”, “Cancel”, or “Save”. Buttons do things, links go places. Refer to guidance on Links vs. buttons
Use action links for calls-to-action. When you want to draw attention to an important call-to-action (CTA) on the page, such as a link that launches a benefit application, use an Action link. Calls-to-action are not actions themselves (see the previous point).
Table of contents. When you want to make a long page of content with two or more H2s easier to navigate, use an On this page link.
Triggering the generation of a PDF. When using for a PDF, use only for linking directly to a PDF, not as a trigger for a process that generates a PDF. For generating a PDF, use a button.

How this component works

Use icons as defined. Icons defined in the link variations above are reserved for that distinct usage. These icons should not be used for another purpose without explicit permission to do so from the Design System Council.

Implementation details

If for some reason you do not use a link web-component links must meet the following criteria:

All links use Source Sans Pro (Regular), underlined, at 16px.
All links share the same color ($color-link-default #004795) for icon, link text, and underline.
All text links should be underlined. This is especially important for low-vision users. (Exception: side navigation links should not be underlined.)

Behavior

Open all links in the same window except in certain instances. Links on VA.gov should open in a new tab only if clicking the link will result in the user losing progress or data. This scenario should be avoided when possible. In all other instances, links should open in the same window. See linking to external sites in the content style guide for additional information.
Use semantically appropriate encodings. Encode email and phone links with mailto: and tel:, respectively.

Choosing between variations

Review “Usage” for guidance.

Content considerations

Refer to the Content Style Guide on Links.

Accessibility considerations

Material honesty. Do not style a link to look or behave like a button (material honesty).
Keyboard navigation. The user must be able to navigate to links using the Tab key and activate links using the Enter key.
Purpose and target. Link text that doesn’t indicate a clear purpose or destination makes it harder for everyone–especially screen reader users–to understand where they’re getting routed off to.
External links must indicate that they are external. Follow the methods detailed in linking to external sites.
- By default, the link component’s external link variation will append the text, “(opens in a new tab)”, instead of using an icon. This follows Techniques for WCAG 2.0 advice on providing users with both a spoken and visual warning that this link opens in a new tab.

Links vs. buttons

Using links and buttons intentionally results in a more inclusive experience for assistive technology users. Make sure to read both buttons and Action Link guidance to determine when you should use each component.
It is important to use Action Links for calls to actions that link to another page rather than buttons, because screen readers always say “link” before links, and “button” before buttons.
A good rule is if the action changes the URL, it should not be a button.
Button and link confusion can be very frustrating for assistive technology users. A user with a screen reader may pull up a list of links and may not find a specific link because it turns out that it’s been designated as a button in the markup.

Link

Examples

Default

Back

Active

Calendar

Channel

Download

Video