Links

Clickable text element to navigate to page section, another page or open an overlaid window such as modal dialog or popover

# Overview

# Default (Medium)

Display within body copy for articles, hub cards, footer, or recommendations.

# Standalone

Display independently with a Call to Action. Some examples are for finding a store, or viewing related products.

# Icon on Left

Display standalone link with icon on left.

# Icon on Right

Display standalone link with icon on right.

# Accessibility

To ensure that usage of this component complies with accessibility guidelines:

  • Always use a <button> element for the tag prop when there is no href attribute that can be applied to the link.to Examples are:
    • Toggling a display to full screen
    • Opening a modal window
    • Triggering a popup menu
    • Playing media content
  • Always use the default <a> element for a link that navigates the user to the location specified by the href attribute
  • Avoid using only “Click here” or “Start here” but if screen space for text is minimal:
    • Provide text that can be read by screen readers
    • Use an inline element for hidden text with the 'cdr-sr-only' class
  <cdr-link>
    Start here <span class="cdr-sr-only">for help finding the proper sleeping bag </span>
  </cdr-link>
1
2
3
  • Ensure assistive technology can find all links on a page:
    • Always provide a href attribute. Empty href attributes are not considered true links
    • Ensure that each link can be accessed using the keyboard. Don’t manipulate the default tab index
    • When using images as links, the alt attribute acts as the link text. Describe the action or hyperlink that the image represents

This component has compliance with following WebAIM’s accessibility guidelines:

  • Using text color with a Level AA contrast ratio of 4.5:1 contrast between the text color and the background but only when displayed on light backgrounds

# Guidelines

# Use When

  • Navigating to another page or a different portion of the same page

# Don't Use When

  • Navigating a user from promotional or campaign content. Instead, use Call to Action

# The Basics

  • Link styles are adapted based on context, such as for links included in the Breadcrumb, Menus, and Navigation
  • There are 2 basic link styles: default and standalone
    • Use the default link when the link is near a body of text or in appears in a body of text
    • Use the standalone link when there is separation from a body of text

# Content

Use link labels that describe the link’s destination when clicked or tapped:

  • Keep link text concise. Restrict link text length to a maximum of 100 characters
  • Use descriptive text for links, so that the user knows where they are going. Avoid using “Click here” or “Start here”
  • If screen space for text is minimal and text is only “Learn more”:
    • Provide alt text that can be read by screen readers
    • For example, if the link text is “Learn more”, then the alt text could be “Learn more about pick up in store”
  • Don’t capitalize links. Some screen readers read capitalized text letter-by-letter. Instead, use sentence case
  • Restrict the number of text links on a page. Screen reader will read all the links on a page

# Behavior

When making decisions about using this component styled as a link or a button, consider the following:

Links Buttons
Answers the question, "Where can I go" Answers the question, "What can I do"
Search engine crawlers can follow anchors for links (<a>) Search engine crawlers cannot follow links that are submitted by input or button
Default keyboard behavior is triggered using the Enter key Default keyboard behavior is triggered using the Space or Enter key
Cannot be disabled like buttons but can be made inert with tabindex="-1" and aria-hidden="true" Can be disabled with disabled attribute

Apply the following use cases when deciding when to use links as anchors or buttons:

Links Buttons
Navigating user to a new page or view Toggling a display to full screen
Changing the URL Opening a modal window
Causing a browser redraw/refresh Triggering a popup menu
Supporting internal page jumps Playing media content

# Do / Don’t

Image showing proper link usage
Do use clear, concise, and descriptive text.
Image showing click here link
Don't use “click here” or “start here” for link text.
The link in this copy uses the cdr-link component, and, so correctly uses an underline
Do underline every link.
The default link in body copy incorrectly does not use an underline
Don't apply different visual treatments for hyperlinks.

# Resources

WebAIM: Links and Hypertext Introduction to Links and Hypertext


# API

# Props

This component will bind any attribute that a native HTML anchor element accepts.

tag

name

string

type

'a'

default

Sets valid HTML element tag. Possible values: { ‘a’ | ‘button’ }

modifier

name

string

type

N/A

default

Modifies the style variant for this component. Possible values: { ‘standalone’ }

href

name

string

type

'#'

default

Sets URL to ‘cdr-link’ href property. The tag prop requires value of <a>.

# Slots

Find more information about using Slots in the article Getting Started as a Developer.

default

name

Sets the innerHTML for CdrLink. This includes text and html markup for icons.

# Events

All event listeners are passed through to/from the component.

# Usage

By default, the component renders using an anchor element and requires an href attribute to render a valid, accessible link.

  <cdr-link href="http://rei.com">
    Visit REI
  </cdr-link>
1
2
3

Use the tag prop to render the link as a <button> element that appears as a link, but without an href attribute.

  <cdr-link tag="button">
    Show Details
  </cdr-link>
1
2
3

# Style Modifier

Following variants are available to the cdr-link modifier attribute:

Value Description
'standalone' Change visual presentation by removing the underline for the normal state. Intended to be use for an independent Call to Action to expand content, remove filters, or provide additional information.