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 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.brand.accent.primary,
  padding: system.padding.md,
  display: 'inline-flex',
  gap: system.gap.md,
});

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

Secondary

Hyperlinks also have a secondary variant. This is a dark gray alternate to the default blue hyperlink. Use this variant when you need to place a Hyperlink on a colored background.

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

const containerStyles = createStyles({
  backgroundColor: system.legacy.color.surface.info.default,
  padding: system.padding.md,
  display: 'inline-flex',
  gap: system.gap.md,
});

export default () => (
  <div className={containerStyles}>
    <Hyperlink variant="secondary" href="#secondary-hyperlink">
      Hyperlink
    </Hyperlink>
  </div>
);

Standalone

Use linkType="standalone" when you need to place a Hyperlink outside of paragraph or body text, such as in a button group or navigation list. This removes the underline. By default, linkType is "inline" and links are underlined.

import {ExternalHyperlink, Hyperlink} 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.gap.md,
});

export default () => (
  <div className={containerStyles}>
    <Hyperlink linkType="standalone" href="#standalone-hyperlink">
      Hyperlink
    </Hyperlink>
  </div>
);

Accessibility Note: Only use linkType="standalone" when something other than color already shows it’s a link — for example, it’s set apart from surrounding content, like in a button or navigation list. Never use linkType="standalone" for links embedded in body copy; a hover-only underline is not enough for inline links to meet WCAG v2.2 success criterion 1.4.1 Use of Color .

In Body Text

In most cases use Hyperlink and ExternalHyperlink with the default linkType="inline" 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 . Do not use linkType="standalone" here, as removing the underline would fail this criterion.

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, externalLinkIcon.

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 globalThis">
    External Hyperlink
  </ExternalHyperlink>
);

ExternalHyperlinks also have an inverse variant. Use this variant when you need to place the link on a dark 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.brand.accent.primary,
  padding: system.padding.md,
  display: 'inline-flex',
  gap: system.gap.md,
});

export default () => (
  <Box cs={parentContainerStyles}>
    <ExternalHyperlink
      href="https://workday.com"
      variant="inverse"
      iconLabel="Opens link in new globalThis"
    >
      Hyperlink
    </ExternalHyperlink>
    <ExternalHyperlink
      href="https://workday.com"
      variant="inverse"
      linkType="standalone"
      iconLabel="Opens new globalThis"
    >
      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 globalThis">
      השועל החום המהיר קופץ מעל הכלב העצל
    </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>
)