Migration Information

For teams migrating from the V1 to V2 component, please refer to the migration guide for changes to the component.

Component Guide

import { Link } from '@uhg-abyss/web/ui/Link';

children

size

fontWeight

variant

href

openNewWindow

// Due to the limitations of the sandbox, the 'alt' and 'alt-underlined' variants are not shown here
// See the "Variants" section for examples of these variants
<Link href="/web/ui/link">
  Link Sandbox
</Link>

Text

The children of the Link component will be rendered as the text of the link.

Link action

Use the href prop to set the route the link will navigate to.

On click

In some cases, a link may need to initiate an action, such as downloading a file, instead of navigate to a path. By omitting the href prop, the link will render as a button and the onClick prop can be used to set a custom function to be triggered when the link is clicked. See the design documentation for more details.

Note that if both href and onClick are present, the component will render as a link. Clicking on it will navigate to the href route and call the onClick function. This is useful for providing side-effect behavior, such as tracking link clicks.

Variant

Use the variant prop to change the styling of the Link. The possible options are 'default', 'underlined', 'alt', and 'alt-underlined'. The 'underlined' and 'alt-underlined' variants should only be used when the Link is embedded in a block of text and/or when using the alt color scheme to provide clear visual distinction. See the design documentation for more details.

Font weight

Use the fontWeight prop to set the text weight of the link. The possible options are 'regular', 'medium', and 'bold'. The default is set to 'medium'.

Size

Use the size prop to set the size of the link. The possible options are 'xs', 'sm', 'md', and 'lg'. The default is set to 'md'.

Inserting elements

To insert an IconSymbol into the Link, use the beforeIcon and afterIcon props. Both props accept either a string (the name of the IconSymbol to use) or an object of the following type:

{
  icon: string;
  variant: 'filled' | 'outlined';
}

Open in a new tab or window

Use the openNewWindow prop to specify whether links open in a new tab or window. By default, openNewWindow is false for relative links, and true for absolute links.

Standard anchor

The Link component has several built in features like router and external link checks. To disable these features and use the Link component as a default anchor tag use the isStandardAnchor prop. This can be useful when using tel or mailto hrefs as well as download links. The default setting is false.

Active links

If a link element href matches the current location path, the class abyss-link-active will be applied to the root element. Use this class to target the styling of an active link. To override the path matching detection, use the isActive prop to directly add the abyss-link-active class to a particular link.

Router Integration

The Link component supports integration with client-side routing frameworks via the routerComponent prop.

Note: React Router integration is handled automatically within Link when using the Abyss routing infrastructure

import NextLink from 'next/link';

<Link routerComponent={NextLink} href="/web/ui/link">
  Next.js navigation
</Link>;

Link Props

Name	Type	Default	Required	Description
afterIcon	"function" | "article" | "code" | "details" | "html" | "iframe" | "input" | "label" | "link" | "map" | "menu" | "output" | "search" | "script" | "select" | "style" | "table" | "title" | ... 3567 more ... | { ...; }	-	-	The IconSymbol to insert at the end of the Link
beforeIcon	"function" | "article" | "code" | "details" | "html" | "iframe" | "input" | "label" | "link" | "map" | "menu" | "output" | "search" | "script" | "select" | "style" | "table" | "title" | ... 3567 more ... | { ...; }	-	-	The IconSymbol to insert at the start of the Link
className	string	-	-	CSS class name to apply to each element within the component
css	Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>	-	-	Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information
data-testid	string	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
disableDefaultProviderProps	boolean	false	-	If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored.
fontWeight	"regular" | "normal" | "$normal" | "medium" | "$medium" | "bold" | "$bold"	'medium'	-	The font weight of the Link
hideIcon	boolean	false	-	If true, the "opens in new window" icon will be hidden
href	string	-	-	The href to navigate to
isActive	boolean	-	-	If true, the Link is considered the active route
isDarkMode	boolean	false	-	If true, use dark mode styles
isStandardAnchor	boolean	false	-	If true, ignore router and external Link checks
onClick	(event: React.MouseEvent<HTMLElement, MouseEvent>) => void	-	-	Callback function executed when the Link is clicked
openNewWindow	boolean	false	-	If true, the Link opens in a new window. By default, external links will open in a new window.
routerComponent	React.ComponentType<any>	-	-	Custom router component to use for client-side navigation (e.g., Next.js Link, Gatsby Link, etc.)
size	"xs" | "$xs" | "sm" | "$sm" | "md" | "$md" | "lg" | "$lg"	'md'	-	The font size of the Link
variant	"default" | "underlined" | "alt" | "alt-underlined"	'default'	-	The visual variant of the Link

Below are the link(s) to the relevant GitHub type files:

Abyss.d.ts

Link.types.ts

Link Classes

Class Name	Description
.abyss-rich-text-editor-controls-button-link-dropdown-text-input-container	Container for the text inputs inside the link dropdown
.abyss-rich-text-editor-controls-button-link-dropdown-display-text-input	Display text input inside the link dropdown
.abyss-rich-text-editor-controls-button-link-dropdown-text-input	URL text input inside the link dropdown
.abyss-rich-text-editor-controls-button-link-dropdown-button-container	Container for the buttons inside the link dropdown
.abyss-rich-text-editor-controls-button-link-dropdown-set-button	Set button inside the link dropdown
.abyss-rich-text-editor-controls-button-link-dropdown-unset-button	Unset button inside the link dropdown
.abyss-rich-text-editor-controls-button-link-tooltip	Tooltip for the link control button
.abyss-rich-text-editor-controls-dropdown-link	Class applied to the link control dropdown when active

Link is built on the standard HTML <a> element for maximum accessibility and compatibility. It provides the icon with alt text for links that open new tabs or windows.

Avoid "Naked" Blue Text Links

Bold blue text is rarely enough by itself to indicate a link, especially in body copy. Use the 'underlined' or 'alt-underlined' variants (following the original HTML standard) or add a decorative icon for maximum accessibility and usability.

Decorative vs. Content Icons

Only when an icon is used as link itself (not recommended), or provides additional information (like the "new window" icons) should it have text alternatives.

Text Alternatives

Do not add text alternatives when the icon duplicates the visible link. Doing so is redundant and will be confusing to screen reader users. If alt text were used in the decorative icon examples below, screen readers would announce the alt text like this:

• "Help graphic Help link"
• "Previous graphic Previous page link"
• "Next Page Next graphic link"

Avoid Using Links for Buttons

Links should only be used for navigating between pages (or their equivalents) on a website.

If the href prop is not defined, links are implemented as HTML <button>s. Use the Button component whenever possible for these cases. This is especially true if the element is not used for site navigation.

Component Tokens

Note: Click on the token row to copy the token to your clipboard.

Search tokens

Link Tokens

Token Name	Value
link.color.text.regular.rest	#196ECF
link.color.text.regular.hover	#004BA0
link.color.text.regular.active	#002677
link.color.text.alt.rest	#FFFFFF
link.color.text.alt.hover	#F3F3F3
link.color.text.alt.active	#E5E5E6
link.color.icon.regular.rest	#196ECF
link.color.icon.regular.hover	#004BA0
link.color.icon.regular.active	#002677
link.color.icon.alt.rest	#FFFFFF
link.color.icon.alt.hover	#F3F3F3
link.color.icon.alt.active	#E5E5E6
link.sizing.all.icon.lg	24px
link.sizing.all.icon.md	20px
link.sizing.all.icon.sm	16px
link.sizing.all.icon.xs	16px
link.spacing.gap.horizontal.container	4px