sp-link

Examples API

Attributes and Properties #

Property Attribute Type Default Description
autofocus autofocus boolean false When this control is rendered, focus it automatically
dir dir 'ltr' | 'rtl' 'ltr'
disabled disabled boolean false Disable this control. It will not receive focus or events
download download string | undefined
href href string | undefined
label label string | undefined
undefined over-background uses over background styles or not
undefined quiet uses quiet styles or not
rel rel string | undefined
size size ElementSize
tabIndex tabIndex number The tab index to apply to this control. See general documentation about the tabindex HTML property
target target '_blank' | '_parent' | '_self' | '_top' | undefined
variant variant 'secondary' | undefined

CSS Custom Properties #

Name Default
--spectrum-link-l-primary-text-size var(--spectrum-global-dimension-font-size-200)
--spectrum-link-m-primary-overbackground-text-color var(--spectrum-alias-text-color-overbackground)
--spectrum-link-m-primary-overbackground-text-color-down var(--spectrum-alias-text-color-overbackground)
--spectrum-link-m-primary-overbackground-text-color-hover var(--spectrum-alias-text-color-overbackground)
--spectrum-link-m-primary-overbackground-text-color-key-focus var(--spectrum-alias-text-color-overbackground)
--spectrum-link-m-primary-text-color var(--spectrum-global-color-blue-600)
--spectrum-link-m-primary-text-color-down var(--spectrum-global-color-blue-700)
--spectrum-link-m-primary-text-color-hover var(--spectrum-global-color-blue-600)
--spectrum-link-m-primary-text-color-key-focus var(--spectrum-alias-text-color-key-focus)
--spectrum-link-m-primary-text-size var(--spectrum-global-dimension-font-size-100)
--spectrum-link-s-primary-text-size var(--spectrum-global-dimension-font-size-75)
--spectrum-link-xl-primary-text-size var(--spectrum-global-dimension-font-size-300)

Description #

An <sp-link> allow users to navigate to a different location. They can be presented in-line inside a paragraph or as a standalone text.

Usage #

See it on NPM! How big is this package in your project? Try it on webcomponents.dev

yarn add @spectrum-web-components/link

Import the side effectful registration of <sp-link> via:

import '@spectrum-web-components/link/sp-link.js';

When looking to leverage the Link base class as a type and/or for extension purposes, do so via:

import { Link } from '@spectrum-web-components/link';

Sizes #

Small
This is an <sp-link size="s" href="#">example link</sp-link>.
Medium
This is an <sp-link size="m" href="#">example link</sp-link>.
Large
This is an <sp-link size="l" href="#">example link</sp-link>.
Extra Large
This is an <sp-link size="xl" href="#">example link</sp-link>.

Variants #

Standard links are blue and should be used to call attention to the link or for when the blue color won’t feel too overwhelming in the experience.

This is a <sp-link href="#">standard link</sp-link>.

The secondary variant is the same color as the paragraph text inline of which it appears. Its subdued appearance is optimal for when the primary variant is too overwhelming, such as in blocks of text with several references linked throughout.

This is a <sp-link href="#" variant="secondary">secondary link</sp-link>.

When a link needs to be placed on top of a colored background or a visual, use the over background link. This link uses a white opaque color instead of a blue color and stands out from the rest of the text with the addition of an underline.

<div
style="background-color: #0f797d; padding: 15px 20px; display: inline-block;"
>

<p style="color: rgb(240, 240, 240);">
This
<sp-link over-background href="#">link</sp-link>
is over a background.
</p>
</div>

All links can have a quiet style, which means they don’t have an underline. This style should only be used when the placement and context of the link is explicit enough that a visible underline isn’t necessary. Quiet links are less accessible, so they should not be used for links that are essential to the experience. These are commonly used in website footers, where there are several lists of links that are shortcuts to other pages.

<p>This is a <sp-link quiet href="#">quiet standard link</sp-link>.</p>
<p>This is a <sp-link quiet variant="secondary" href="#">quiet secondary link</sp-link>.</p>
<div
style="background-color: #0f797d; padding: 15px 20px; display: inline-block;"
>

<p style="color: rgb(240, 240, 240);">
This is a
<sp-link over-background quiet href="#">quiet link</sp-link>
over a background.
</p>
</div>

Download attribute #

The download attribute on an <a> tag prompts a user to download a link as opposed to navigating to it. This attribute has been carried forward to <sp-link> to function the same.

While it functions this way without assigning a value, actually assigning the value allows custom naming of the download link in accordance with standard <a> rules defined by the browser.

This is a <sp-link download="myfile.txt" href="#">download link</sp-link>.

Accessibility #

Links are accessible by default, rendered in HTML using the <a> element. The correct aria roles will automatically be applied.