Components
Link
Use: DeployedExamples
Default
Active
View active va-link in Storybook
Calendar
View calendar va-link in Storybook
Channel
View channel va-link in Storybook
Download
View download va-link in Storybook
Video
View video va-link in Storybook
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 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 in the same window except in certain instances. Links should only open in a new tab if clicking the link will result in the user losing progress or data. Otherwise, links should open in the same window.
- Use semantically appropriate encodings. Encode email and phone links with
mailto:
andtel:
, respectively.
Choosing between variations
Review “Usage” for guidance.
Content considerations
Links should tell people what action to take, where to go next, or what information to expect when they select the link.
- Use natural and descriptive language.
- Hyperlink the most relevant word or phrase that describes the purpose and target (destination) of the link.
- Don’t make the link so long that the relevant words get lost.
- Avoid “Click here” as the CTA text.
- Avoid generic CTA links like “Learn more,” “See more,” and “Read more” by themselves.
- Don’t punctuate standalone CTA links. Exception: When the link text is a question.
- If the embedded link text comes at the end of a sentence, don’t hyperlink the ending punctuation.
- When a link opens a PDF, YouTube video, XLS or other file format, use the appropriate link variation.
Like this
Use natural language, and link relevant words
If your disability gets worse, file for a VA disability compensation increase.
Apply for a United States burial flag to place over a casket or coffin, or place with an urn. Learn more about burial flags
Not this
Avoid “click here” and generic CTA text
Click here to file for a VA disability compensation increase if your disability gets worse.
Apply for a United States burial flag to place over a casket or coffin, or place with an urn. Learn more
Embedded text links vs. CTA links
Use embedded text links to cross-link related, helpful information
Embedded text links are hyperlinks that are part of running text in body copy. We use them to link people to related, but not essential, information.
- Because too many embedded links can be distracting or overwhelming to readers with traumatic brain injuries or other cognitive impairments, we try to not overuse them.
- Link information when it will be helpful to the Veteran, and it’s related to the subject being discussed, not just for the sake of linking.
Use CTA links to call out actions
CTA links are standalone hyperlinks that are calls to an action, but that don’t warrant a primary button CTA.
We generally reserve button CTAs to launch an application, to sign in, or other primary, essential action on a page. But there are other kinds of actions that may call for a CTA as a text link, like downloading a form, learning about important information (like eligibility or copay rates, etc.).
Like this
In this example, the link is an action related to the topic, but it isn’t the primary CTA, which is to use the online application.
You can apply online or mail your Application for Burial Benefits (VA Form 21P-530).
Not this
In this example, the action gets lost as an embedded text link.
You can apply online or mail your Application for Burial Benefits (VA Form 21P-530).
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: Without a purpose and target, everyone– but especially screen reader users– will struggle to understand where they may be routed off to.
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.