Link

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

Examples

Base

Link

Web Component
HTML Blueprint

<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

Web Component
HTML Blueprint

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

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

No Underline on Hover

Use to remove a link's underline on hover.

Link

Web Component
HTML Blueprint

<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

Web Component
HTML Blueprint

<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

Web Component
HTML Blueprint

<chi-link href="#">
  <chi-icon icon="circle-question-outline"></chi-icon>
  <span>Help</span>
</chi-link>

<a class="chi-link" href="#">
  <div class="chi-link__content">
    <i class="chi-icon icon-circle-question-outline" aria-hidden="true"></i>
    <span>Help</span>
  </div>
</a>

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.

Web Component
HTML Blueprint

<chi-link href="#" alternative-text="View helpful information about this topic">
  <chi-icon icon="circle-question-outline"></chi-icon>
</chi-link>

<a class="chi-link" href="#" aria-label="View helpful information about this topic">
  <div class="chi-link__content">
    <i class="chi-icon icon-circle-question-outline" aria-hidden="true"></i>
  </div>
</a>

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

Web Component
HTML Blueprint

<!-- 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

Web Component
HTML Blueprint

<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

Web Component
HTML Blueprint

<!-- 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

Web Component
HTML Blueprint

<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.

Link

Web Component
HTML Blueprint

<!-- 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`
`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

Key	Function
`Tab`	Moves focus to the next focusable element
`Shift + Tab`	Moves focus to the previous focusable element
`Enter`	Activates the link

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

Visit WebAIM for keyboard techniques.

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.

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.

Role	Attribute	Element	Usage
`link`	-	`span`,`img`	Identifies the `span`/`img` element as a link.
-	`tabIndex="0"`	`span`,`img`	Includes the link element in the page Tab sequence.
-	`alt`	`img`	Defines the accessible name of the link.
-	`aria-label`	`span`	Defines the accessible name of the link.

Resources

W3 Link Example: Contains comprehensive details regarding the accessibility behavior of the link.
A11y Style Guide: Gives core recommendations for accessible links.
Mozilla Resources for Developers: Find examples of accessible links.

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)