Skip to main content

Link

Styled hyperlink with classless defaults, automatic new-window and file-type indicator icons, and a reset decoration for a link that should inherit its surroundings instead.

Usage​

When to use

  • Any anchor tag inside body content. A plain <a> picks up the design system treatment.
  • When the consumer wants external, new-window, or file-type indicators to appear automatically from attribute selectors
  • When a specific link should opt out of the automatic indicator icon - add .plain
  • When a link should drop link styling entirely and inherit the surrounding text, such as a brand name in a header - add .reset

When not to use

  • As a call-to-action - use the button component with a link appearance
  • Inside a navigation menu - navbar and sidenav bring their own link treatment
  • Inside a linklist - the linklist component overrides link styling for its rows

Do

  • Make the link text describe the destination so the link makes sense out of context
  • Provide an aria-label that includes "opens in new tab" on target="_blank" links when the visible text does not already say so

Don't

  • Use "click here" or "read more" as link text
  • Rely on color alone to indicate a link - the underline is part of the affordance

API​

Slots​

SlotRequiredDescription
contentYesVisible link text.

Props​

PropTypeDefaultDescription
urlstring#href value for the anchor.
is_currentboolean-Adds aria-current="page" for the active or current link.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.subtleEmphasis-Lower emphasis; a muted, quieter weight.
.neutralEmphasisYesDefault emphasis; the standard weight at balanced contrast.
.accentEmphasis-Higher emphasis; a stronger, louder weight.
.infoIntent-Informational message.
.warningIntent-Warning or caution.
.dangerIntent-Error, destructive, or critical.
.successIntent-Confirmation or completion.
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.plainDecoration-plain suppresses the automatic new-window and file-type indicator icons; reset drops the link color, underline, background and transition so the link inherits the surrounding text.
.resetDecoration-plain suppresses the automatic new-window and file-type indicator icons; reset drops the link color, underline, background and transition so the link inherits the surrounding text.

Examples​

Active page​

Active link using aria-current="page".

Reset​

.reset drops the link color, underline, background and transition, so the link reads as the text around it.

In body​

Links inside running prose, where the underline and the visited color have to hold against the surrounding text.

Accessibility​

  • WCAG 2.2 AA
  • Link color meets contrast on both schemes; visited color also meets contrast.
  • Visible focus ring on keyboard focus
  • The automatic new-window and file-type indicator icons are decorative - rendered via ::after and mask-image, so screen readers ignore them. Pair a truly important external link with a visible-text cue (or aria-label) rather than relying on the icon alone.
  • button - call-to-action styling
  • linklist - stacked list of navigation links
  • navbar - site navigation menus