Skip to main content

Standalone link

The Standalone link elements, with their href property, create a hyperlink to web pages, files, email addresses, locations in the same page, or anything else a URL can address.

Content within each standalone link should indicate the link's destination. If the href attribute is present, pressing Enter while focused on the inline link will activate it.

— Definition from the MDN web docs

Usage​

Standalone links can be used as an isolated element:

Loading...
Live Editor
<qds-standalone-link href="/example">Standalone example</qds-standalone-link>

Writing guidelines​

Follow the 4Ss from NNGroup guidelines for writing good link labels:

  • Specific: tell users what they will find at the destination.
  • Sincere: what the link promises is found at the destination
  • Substantial: the link destination is clear even when not reading the surrounding text (e.g. when users scan the page).
  • Succinct: keep links short without sacrificing the other principles. Frontload links with information-carrying language.

Link targets work in the same way as in the inline link. Here is the link where you can see all the information.

Icon​

A Standalone Link can include a leading icon. Choose icons that add meaning and clarity to the action described in the link's text. Use the icon-name property to display an icon on the button. Quartz will look into the default icon library unless you specify another library using the icon-library property.

In Figma, enable the 🅵 icon toggle to see the icon-name property. See the Usage > Icons instructions for more details.

Loading...
Live Editor
<qds-standalone-link icon-name="checked" icon-library="core" href="/example">
  Standalone icon example
</qds-standalone-link>

Size​

Standalone links follow the transversal control size principles. It is recommended to use a standard size, but you can also choose between a small and large option.

Loading...
Live Editor
<qds-standalone-link size="standard" href="/example">
  Standalone size example
</qds-standalone-link>

Importance​

It is possible to choose how the standalone links are shown using this property importance (standard, subdued or emphasized). You can follow the transversal Importance principle through its importance property.

Standard​

The standard is the default option in which you see the link in a different color. (It doesn't need to be specified).

Loading...
Live Editor
<div className="qds-controls qds-related flex-row">
  <qds-standalone-link importance="standard" href="/example">
    Standalone standard importance example
  </qds-standalone-link>
  <qds-standalone-link importance="subdued" href="/example">
    Standalone subdued importance example
  </qds-standalone-link>
  <qds-standalone-link importance="emphasized" href="/example">
    Standalone emphasized importance example
  </qds-standalone-link>
</div>

Subdued​

The subdued option does not change the color of the link text.

Loading...
Live Editor
<qds-standalone-link importance="subdued" href="/example">
  Standalone subdued importance example
</qds-standalone-link>

Emphasized​

The emphasized option changes the color of the link text and adds a chevron icon in the end of the link.

Loading...
Live Editor
<qds-standalone-link importance="emphasized" href="/example">
  Standalone emphasized importance example
</qds-standalone-link>

Implementation tips​

Security and privacy​

<qds-standalone-link> elements can have consequences for users' security and privacy. Make sure to read and understand the Referer header: privacy and security concerns guidelines.

Importing​

Note: if you're using the lazy loader to load Quartz components, you can ignore this section.

To import this component from the public jsDeliver CDN using a JavaScript import:

import { defineCustomElementQdsStandaloneLink } from 'https://cdn.jsdelivr.net/npm/@quartzds/core@next+esm'
defineCustomElementQdsStandaloneLink()

Component reference​

Properties​

Attribute / PropertyTypeDescriptionDefault
disabled
boolean

Prevents the standalone link from being interacted with: it cannot be pressed or focused.

false
download
boolean | string | undefined

Causes the browser to treat the linked URL as a download. Can be used with or without a filename value:

  • Without a value, the browser will suggest a filename/extension, generated from various sources:

  • filename: defining a value suggests it as the filename. / and \ characters are converted to underscores (_). Filesystems may forbid other characters in filenames, so browsers will adjust the suggested name if necessary.

undefined
href
string | undefined

The URL that the standalone link points to. Standalone links are not restricted to HTTP-based URLs — they can use any URL scheme supported by browsers:

  • Sections of a page with document fragments
  • Specific text portions with text fragments
  • Pieces of media files with media fragments
  • Telephone numbers with tel: URLs
  • Email addresses with mailto: URLs
  • While web browsers may not support other URL schemes, websites can with registerProtocolHandler()
undefined
hreflang
string | undefined

Hints at the human language of the linked URL. No built-in functionality. Allowed values are the same as the global lang attribute.

undefined
icon-library / iconLibrary
string

The name of a registered icon library.

'default'
icon-name / iconName
string | undefined

The name of the icon to render.

Available names depend on the icon library being used.

undefined
importance
"emphasized" | "standard" | "subdued" | undefined

The standalone link's importance.

'standard'
referrerpolicy / referrerPolicy
"" | "no-referrer" | "no-referrer-when-downgrade" | "origin" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url" | undefined

How much of the referrer to send when following the standalone link.

  • no-referrer: The Referer header will not be sent.
  • no-referrer-when-downgrade: The Referer header will not be sent to origins without TLS (HTTPS).
  • origin: The sent referrer will be limited to the origin of the referring page: its scheme, host, and port.
  • origin-when-cross-origin: The referrer sent to other origins will be limited to the scheme, the host, and the port. Navigations on the same origin will still include the path.
  • same-origin: A referrer will be sent for same origin, but cross-origin requests will contain no referrer information.
  • strict-origin: Only send the origin of the document as the referrer when the protocol security level stays the same (HTTPS→HTTPS), but don't send it to a less secure destination (HTTPS→HTTP).
  • strict-origin-when-cross-origin (default): Send a full URL when performing a same-origin request, only send the origin when the protocol security level stays the same (HTTPS→HTTPS), and send no header to a less secure destination (HTTPS→HTTP).
  • unsafe-url: The referrer will include the origin and the path (but not the fragment, password, or username). This value is unsafe because it leaks origins and paths from TLS-protected resources to insecure origins.
undefined
rel
string | undefined

The relationship of the linked URL as space-separated link types.

The following list includes some of the most important existing keywords. Every keyword within a space-separated value should be unique within that value.

  • alternate: Alternate representations of the current document.
  • author: Author of the current document or article.
  • bookmark: Permalink for the nearest ancestor section.
  • external: The referenced document is not part of the same site as the current document. An icon will be rendered next to the text if this value is specified.
  • help: Link to context-sensitive help.
  • license: Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
  • me: Indicates that the current document represents the person who owns the linked content.
  • next: Indicates that the current document is a part of a series and that the next document in the series is the referenced document.
  • nofollow: Indicates that the current document's original author or publisher does not endorse the referenced document.
  • noopener: Creates a top-level browsing context that is not an auxiliary browsing context if the hyperlink would create either of those, to begin with (i.e., has an appropriate target attribute value).
  • noreferrer: No Referer header will be included. Additionally, has the same effect as noopener.
  • opener: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has "_blank" as target attribute value).
  • prev: Indicates that the current document is a part of a series and that the previous document in the series is the referenced document.
  • search: Gives a link to a resource that can be used to search through the current document and its related pages.
  • tag: Gives a tag (identified by the given address) that applies to the current document.
undefined
size
"large" | "small" | "standard" | undefined

The standalone link's size.

'standard'
target
"_blank" | "_parent" | "_self" | "_top" | string & Record<never, never> | undefined

Where to display the linked URL, as the name for a browsing context (a tab, window, or <iframe>. The following keywords have special meanings for where to load the URL:

  • _blank: usually a new tab, but users can configure browsers to open a new window instead.
  • _parent: the parent browsing context of the current one. If no parent, behaves as _self.
  • _self: the current browsing context.
  • _top: the topmost browsing context (the "highest" context that's an ancestor of the current one). If no ancestors, behaves as _self.
undefined

Events​

EventTypeDescriptionBubblesCancelableComposedqdsBlur
{ readonly relatedTarget: EventTarget | null; }

Emitted when the standalone link loses focus.

qdsFocus
{ readonly relatedTarget: EventTarget | null; }

Emitted when the standalone link gains focus.

Last updated on