Link

Use Links to navigate between pages, locations within the same page, and more.

Examples

Base

Link
<chi-link href="#">Link</chi-link>
<a class="chi-link" href="#">Link</a>

Disabled

Make links appear inactive by adding the disabled boolean attribute or -disabled class.

Link
<chi-link href="#" disabled>Link</chi-link>
<a class="chi-link -disabled" href="#">Link</a>

No Underline

Use to remove a link's underline.

Link
<chi-link href="#" no-underline>Link</chi-link>
<a class="chi-link -no-underline" href="#">Link</a>

No Underline on Hover

Use to remove a link's underline on hover.

Link
<chi-link href="#" no-hover-underline>Link</chi-link>
<a class="chi-link -no-hover-underline" href="#">Link</a>

CTA

Call to action (CTA) links are prominent links used primarily on marketing web pages to encourage users to perform a specific action (e.g. Get started, Learn more). Use link sizes to render CTA links larger or smaller.

Learn more
<chi-link href="#" cta>Learn more</chi-link>
<a class="chi-link -cta" href="#">Learn more</a>

Labeled Icon Link

Use labeled icon links to render both text and icons inside link tags.

Help

Icon Link

Use icon links to render icons inside link tags. Note: All icon links without text labels must define a label in the alternative-text attribute for accessibility.

Target

Use target to specify where to open a link. Supported values are: _self, _blank, _parent, _top, or a custom named frame framename. The default value is _self.

Link
<!-- Open a link in the same frame as it was clicked (default) -->
<chi-link href="#" target="_self">Link</chi-link>

<!-- Open a link in a new window or tab -->
<chi-link href="#" target="_blank">Link</chi-link>

<!-- Open a link in the parent frame -->
<chi-link href="#" target="_parent">Link</chi-link>

<!-- Open a link in the full body of the window -->
<chi-link href="#" target="_top">Link</chi-link>

<!-- Open a link in a custom named frame -->
<chi-link href="#" target="framename">Link</chi-link>
<!-- Open a link in the same frame as it was clicked (default) -->
<a class="chi-link" href="#" target="_self">Link</a>

<!-- Open a link in a new window or tab -->
<a class="chi-link" href="#" target="_blank">Link</a>

<!-- Open a link in the parent frame -->
<a class="chi-link" href="#" target="_parent">Link</a>

<!-- Open a link in the full body of the window -->
<a class="chi-link" href="#" target="_top">Link</a>

<!-- Open a link in a custom named frame -->
<a class="chi-link" href="#" target="framename">Link</a>

Rel

Use rel to set the relationship between the current page and the linked page. Rel supports all HTML a attribute values. Examples include: alternate, external, next, nofollow, noreferrer, noopener, prev, and more.

Link
<chi-link href="#" rel="noopener">Link</chi-link>
<a class="chi-link" href="#" rel="noopener">Link</a>

Download

Use download to prompt users to save a page or document instead of navigating to it. The download attribute accepts an optional value used to name the file. If no value is provided, the original filename is used.

Link
<!-- Use default filename -->
<chi-link href="#" download>Link</chi-link>

<!-- Specify custom filename -->
<chi-link href="#" download="custom-filename">Link</chi-link>
<!-- Use default filename -->
<a class="chi-link" href="#" download>Link</a>

<!-- Specify custom filename -->
<a class="chi-link" href="#" download="custom-filename">Link</a>

Hreflang

Use to set the language of the link.

Link
<chi-link href="#" hreflang="en">Link</chi-link>
<a class="chi-link" href="#" hreflang="en">Link</a>

Additional Sizes

Links support the following sizes: xs, sm, md, lg, and xl. By default, links inherit the font-size of their parent element.

xs

Link

sm

Link

md

Link

lg

Link

xl

Link
<!-- xs -->
<chi-link href="#" size="xs">Link</chi-link>

<!-- sm -->
<chi-link href="#" size="sm">Link</chi-link>

<!-- md -->
<chi-link href="#" size="md">Link</chi-link>

<!-- lg -->
<chi-link href="#" size="lg">Link</chi-link>

<!-- xl -->
<chi-link href="#" size="xl">Link</chi-link>
<!-- xs -->
<a class="chi-link -xs" href="#">Link</a>

<!-- sm -->
<a class="chi-link -sm" href="#">Link</a>

<!-- md -->
<a class="chi-link -md" href="#">Link</a>

<!-- lg -->
<a class="chi-link -lg" href="#">Link</a>

<!-- xl -->
<a class="chi-link -xl" href="#">Link</a>

Web Component

Properties

Property
Attribute
Description
Type
Default
alternativeText
alternative-text
to provide alternative text in case of icon links.
string
undefined
cta
cta
to render a link as a prominent call to action.
boolean
false
disabled
disabled
to disable a link.
boolean
false
download
download
to prompt users to save a page or document instead of navigating to it.
string
undefined
href
href
to set a link's destination url.
string
'#'
hreflang
hreflang
to set the language of a link's destination url.
string
undefined
noHoverUnderline
no-hover-underline
to remove a link's underline on hover.
boolean
false
noUnderline
no-underline
to remove a link's underline.
boolean
false
rel
rel
to set the relationship between the current page and the linked page.
string
undefined
size
size
to set size of a link { xs, sm, md, lg, xl }.
string
undefined
target
target
to set target of a link.
string
undefined

Accessibility

Keyboard Navigation

KeyFunction
TabMoves focus to the next focusable element
Shift + TabMoves focus to the previous focusable element
EnterActivates the link

For comprehensive details on keyboard support for buttons, refer to our Keyboard Control Guide.

Visit WebAIM for keyboard techniques.

Guidance for developers
  • Always start with the a tag for links. This tag is inherently designed to create hyperlinks, allowing users to navigate from one page or section to another.
  • Ensure every link has a valid href attribute. This attribute should contain the URL or anchor link the user will navigate to when the link is activated.
  • When using target="_blank" to open links in a new tab, add rel="noopener noreferrer" for security reasons and to protect user privacy.
  • Use ARIA roles and properties correctly to ensure assistive technologies can accurately convey the link's purpose. Avoid redundant roles like role="link" on anchor elements.
  • Avoid generic text like "click here" or "read more." Instead, use meaningful descriptions that convey the purpose of the link without needing surrounding content for context.
  • For links with generic text, use aria-describedby or aria-labelledby to associate the link with additional contextual text, providing more clarity on the link's purpose.
Guidance for designers
  • Clear Link Text: Design with descriptive text for links. Avoid generic phrases like "click here," ensuring users understand the link's destination.
  • Visual Distinction: Ensure links are visually distinct from regular text through color, underlining, or other styling cues to indicate interactiveness.
  • Contrast Ratios: Maintain high contrast ratios between link text and its background to ensure readability for users with visual impairments.
  • Indicate Link Behavior: Visually indicate if a link will open in a new window or tab, using icons or text. This informs users of the expected behavior.
  • Consistent Styling: Apply consistent styles for links across the application or website to avoid confusion about what is clickable.

Find live examples in the A11y style guide.

Roles and attributes

Below are some key considerations to ensure that our components are fully accessible in various scenarios within your interfaces. These points outline the necessary roles and attributes to keep in mind.

RoleAttributeElementUsage
link-span,imgIdentifies the span/img element as a link.
-tabIndex="0"span,imgIncludes the link element in the page Tab sequence.
-altimgDefines the accessible name of the link.
-aria-labelspanDefines the accessible name of the link.

Resources

Other recommendations

Explore additional accessibility tips in the general Accessibility Guide.

WCAG 2.2 Guidelines

  • Non-text Content: All non-text content that is presented to the user has a text alternative that serves the equivalent purpose. (Level A)
  • Info and Relationships: Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. (Level A)
  • Headings and Labels: Headings and labels describe topic or purpose. (Level AA)
  • Labels or Instructions: Labels or instructions are provided when content requires user input. (Level A)
  • Name, Role, Value: For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies. (Level A)