Hyperlink

Anatomy

1. Text: Describes where the link goes.
2. Underline (conditional): Appears when the link is inline with body text.
3. External link icon (conditional): extLink system icon that appears when the link navigates to a different site entirely.

Usage Guidance

Hyperlinks (also known as links) are interactive elements that navigate somewhere else, such as another page, or a different site entirely. Links may also act as anchor tags that navigate to users to sections on the same page, like in a table of contents.

Hyperlinks may appear inline with body text or as a standalone link. When a hyperlink is used inline with body text, an underline is used to differentiate it from surrounding text to avoid relying on color alone to communicate interactivity.

When to Use

• Use a Hyperlink to navigate to a different page or view within the app
• Use an External Hyperlink to navigate to a different site entirely. External Hyperlinks are indicated by an extLink system icon placed at the end.
• Hyperlinks may be used as anchor tags to navigate to different sections on a page.
• Use a standalone Hyperlink when you need to place a Hyperlink outside of a paragraph or body text. This will remove the underline.

When to Use Something Else

• Use a Button for any action that changes state or triggers a process or workflow.
• Use Tabs to organize and switch between related sections on the same page. Tabs hide content to preserve screen real estate.
• Use Breadcrumbs to expose and navigate a hierarchy of pages.

Examples

Hyperlink

Hyperlinks should be used when you want to navigate away from the current page or to an anchor on the current page. By default, Hyperlinks have an underline for accessibility.

import {Hyperlink} from '@workday/canvas-kit-react/button';

export default () => <Hyperlink href="#hyperlink">Hyperlink</Hyperlink>;

Inverse

Hyperlinks also have an inverse variant. Use this variant when you need to place a Hyperlink on a dark or colorful background.

import React from 'react';

import {Hyperlink} from '@workday/canvas-kit-react/button';
import {Box} from '@workday/canvas-kit-react/layout';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const parentContainerStyles = createStyles({
  backgroundColor: system.color.bg.primary.default,
  padding: system.space.x4,
  display: 'inline-flex',
  gap: system.space.x4,
});

export default () => (
  <Box cs={parentContainerStyles}>
    <Hyperlink href="#hyperlink" variant="inverse">
      Hyperlink
    </Hyperlink>
    <Hyperlink href="#hyperlink" variant="standaloneInverse">
      Hyperlink
    </Hyperlink>
  </Box>
);

Standalone

Hyperlinks also have a standalone variant. Use this variant when you need to place a Hyperlink outside of a paragraph or body text. This will remove the underline.

This variant can also be used with the ExternalHyperlink component.

import {Hyperlink, ExternalHyperlink} from '@workday/canvas-kit-react/button';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const containerStyles = createStyles({
  display: 'inline-flex',
  gap: system.space.x4,
});

export default () => (
  <div className={containerStyles}>
    <Hyperlink variant="standalone" href="#standalone-hyperlink">
      Standalone Hyperlink
    </Hyperlink>
    <ExternalHyperlink
      variant="standalone"
      href="#standalone-external-hyperlink"
      iconLabel="Opens new window"
    >
      Standalone External Hyperlink
    </ExternalHyperlink>
  </div>
);

In Body Text

In most cases use HyperLink and ExternalHyperlink in body text of a sentence where you need to link to another page or part of the document. By default they will wrap to a new line.

import {Hyperlink} from '@workday/canvas-kit-react/button';

export default () => (
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
    <Hyperlink href="#hyperlink">tempor incididunt</Hyperlink> ut labore et dolore magna aliqua. Ut
    enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
    consequat. Duis aute irure dolor in reprehenderit in
    <Hyperlink href="#hyperlink">voluptate velit esse cillum dolore eu fugiat</Hyperlink>
    nulla pariatur.
  </p>
);

Accessibility Note: Underlining links is not required in most cases. However, the example above is one such exception. When hyperlinked text appears inline with static text, a text decoration is required to avoid failing WCAG v2.2 success criterion 1.4.1 Use of Color.

Failure of Success Criterion 1.4.1 due to creating links that are not visually evident without color vision

Accessibility

Our link components render semantic HTML <a> elements to the browser DOM. This means that ARIA roles won’t be necessary in most cases. The href prop is required for accessibility. Activation links with the Enter key is standard expected behavior, while Space is only expected for buttons.

When to Use Links vs Buttons

• Use Hyperlinks when: Navigating to different pages or sections, or changing the browser’s location
• Use Buttons when: Performing actions like submitting forms, opening modals, or triggering functions without navigation
• Why This Matters: Screen reader users expect different behaviors from links vs buttons. Users navigate between links using different keyboard shortcuts than buttons. Browser behaviors like “Open in new tab” only work with proper links.

Common Mistakes to Avoid

• Using buttons styled as links for navigation (breaks right-click context menus)
• Using links for actions like “Delete” or “Save” (confuses user expectations)
• Missing href attributes on navigation elements (breaks keyboard accessibility)
• Using href="#" with onClick handlers instead of proper buttons

Component API

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

ExternalHyperlink

If your link should open in a new tab or window use the ExternalHyperlink component. It will let users know about the behavior by adding an icon, extLinkIcon.

Accessibility Note: Providing a label to the icon via the iconLabel prop is required for accessibility because the icon adds meaning to the link text. We recommend keeping the alt text as concise as possible, such as “Opens new window”. This override will be needed for translations.

import {ExternalHyperlink} from '@workday/canvas-kit-react/button';

export default () => (
  <ExternalHyperlink href="https://workday.com" iconLabel="Opens new window">
    External Hyperlink
  </ExternalHyperlink>
);

ExternalHyperlinks also have an inverse variant. Use this variant when you need to place the link on a dark or colorful background.

import React from 'react';

import {ExternalHyperlink} from '@workday/canvas-kit-react/button';
import {Box} from '@workday/canvas-kit-react/layout';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const parentContainerStyles = createStyles({
  backgroundColor: system.color.bg.primary.default,
  padding: system.space.x4,
  display: 'inline-flex',
  gap: system.space.x4,
});

export default () => (
  <Box cs={parentContainerStyles}>
    <ExternalHyperlink
      href="https://workday.com"
      variant="inverse"
      iconLabel="Opens link in new window"
    >
      Hyperlink
    </ExternalHyperlink>
    <ExternalHyperlink
      href="https://workday.com"
      variant="standaloneInverse"
      iconLabel="Opens new window"
    >
      Hyperlink
    </ExternalHyperlink>
  </Box>
);

ExternalHyperlinks will also flip the icon for right-to-left (RTL) languages.

import {ExternalHyperlink} from '@workday/canvas-kit-react/button';
import {CanvasProvider, ContentDirection} from '@workday/canvas-kit-react/common';

export default () => (
  <CanvasProvider theme={{canvas: {direction: ContentDirection.RTL}}}>
    <ExternalHyperlink href="https://workday.com" iconLabel="Opens link in new window">
      השועל החום המהיר קופץ מעל הכלב העצל
    </ExternalHyperlink>
  </CanvasProvider>
);

Component API

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

Specifications

Content Guidelines

Coming soon!

Anatomy

1. Text
2. Underline: Indicates interactivity and differentiates link from surrounding text.

Usage Guidance

When to Use

• Use the Hyperlink to illustrate text interactivity and the affordance of redirection to an external page.
• Use the Hyperlink to provide users access to an external page when the ability to investigate further information or access an external functionality offers a reasonable benefit.

When to Consider Something Else

• Consider reviewing the content hierarchy if more than one Hyperlink is used in a contiguous piece of text. Overuse of Hyperlinks in a piece of text can lead to issues with mistapping.
• Use the Tertiary Button for internal redirects instead of Hyperlink. Although Hyperlink and Tertiary Button appear similar, they have different intended purposes reflected by the differences in their interaction behaviors. Compared to (1) Hyperlink, the active (2) Tertiary Button behaves as a more typical button — developing a pill-shaped background fill upon interaction:

Text Sizing

When using Hyperlinks, carefully consider the text size. Hyperlinks are intended for use in body text. Avoid using Hyperlinks in subtext due to tap targets overlapping line heights.

Internal vs. External Redirection

Additional Affordances

The blue color of a hyperlink is a well-known affordance of tappability among users. Avoid the use of additional identifiers that indicate an item as a hyperlink or an external navigation outlet.

API Guidelines

Methods

Class name: TextWithHyperlinks Module name: UIComponentsPlugin

    public init(
        featureData: FeatureMetricsData,
        attributedString: AttributedString,
        fontToken: Typography,
        fontWeight: Typography.Weight = .regular,
        linkConfigurations: [TextWithHyperlinksInternal.LinkConfiguration]
    )

Parameters

Anatomy

1. Text
2. Underline: Indicates interactivity and differentiates link from surrounding text.

Usage Guidance

When to Use

• Use the Hyperlink to illustrate text interactivity and the affordance of redirection to an external page.
• Use the Hyperlink to provide users access to an external page when the ability to investigate further information or access an external functionality offers a reasonable benefit.

When to Consider Something Else

• Consider reviewing the content hierarchy if more than one Hyperlink is used in a contiguous piece of text. Overuse of Hyperlinks in a piece of text can lead to issues with mistapping.
• Use the Tertiary Button for internal redirects instead of Hyperlink. Although Hyperlink and Tertiary Button appear similar, they have different intended purposes reflected by the differences in their interaction behaviors. Compared to (1) Hyperlink, the active (2) Tertiary Button behaves as a more typical button — developing a pill-shaped background fill upon interaction:

Text Sizing

When using Hyperlinks, carefully consider the text size. Hyperlinks are intended for use in body text. Avoid using Hyperlinks in subtext due to tap targets overlapping line heights.

Internal vs. External Redirection

Additional Affordances

The blue color of a hyperlink is a well-known affordance of tappability among users. Avoid the use of additional identifiers that indicate an item as a hyperlink or an external navigation outlet.

API Guidelines

Methods

  fun TextWithHyperlinksUiComponent(
    modifier: Modifier = Modifier,
    content: String,
    linkConfigurations: List<LinkConfiguration>,
    textStyle: TextStyle = LocalTextStyle.current
  )

Parameters