Skip to content

Link

Hyperlinks between pages.

See this section for upgrading from the legacy link component
Using onClick
Code Editor
Disabled link
Code Editor

Link can wrap any element.

Code Editor
Blend variant works well with themed components.
Code Editor

Upgrading from LegacyLink to Link

Important Considerations

While at the end of the day, both components present the user with a clickable anchor link, there are small differences between the two.

Wrapping links around the end of a line

Differences in `display`
Legacy Link
Link
display: inline-flex
display: inline /* the default for <a> */

LegacyLink has no way to break/wrap around at the end of a line, whereas Link will successfully do so.

Make use of sending href={undefined}

Using `href` incorrectly can introduce flaky Playwright integration and end-to-end tests.

Link is able to handle the omission of `href`. When this happens, the Link component renders as a <span> instead of a link. This behavior is useful for when the `href` depends on data that has not yet arrived (such as waiting on the router or an API response) to make sure that the user is not provided an incorrect link. An example is shown in the table below.

Incorrect usage

We don't want to link the user to be directed to '/personal' unless it is 100% certain that '/personal' is the correct link for the user's current scope.

// router.query takes a moment to resolve
const { team } = router.query;
const href = team ? '/team/' + team : '/personal';
return <Link href={href}>Example</Link>;

Correct usage

While the router is loading, it is possible to set `href` to `undefined` until it is clear which scope the user is currently in.

// router.query takes a moment to resolve
const { team } = router.query;
let href = undefined;
if (router.isReady) {
  href = team ? '/team/' + team : '/personal';
}
return <Link href={href}>Example</Link>;

No change needed

Default
Legacy Link
Link
Default linkDefault link
<LegacyLink href="#">
  Default link
</LegacyLink>
<Link href="#">
  Default link
</Link>
Code Editor

Pass `undefined` to disable a link (useful when the URL cannot be constructed until data is fetched)

`LegacyLink` does not support this functionality
Undefined/no `href`
Legacy Link
Link
Link with no linkLink with no link
<LegacyLink href="some-placeholder">
  Link with no link
</LegacyLink>
<Link>
  Link with no link
</Link>
Code Editor
The new Link component adds an underline for the hover state

Use the "secondary" variant

The new Link component's “secondary” variant's hover state is a text color change rather than underline
Underline Hover State
Legacy Link
Link
Link with hover stateLink with hover state
<LegacyLink href="#" underline>
  Link with hover state
</LegacyLink>
<Link href="#" variant="secondary">
  Link with hover state
</Link>
Code Editor

Use the "highlight" variant

Open in New Tab
Legacy Link
Link
Link that opens in new tabLink that opens in new tab
<LegacyLink external href="#">
  Link that opens in new tab
</LegacyLink>
<Link href="#" tab>
  Link that opens in new tab
</Link>
Code Editor
Show External Icon
Legacy Link
Link
Link with external iconLink with external icon
<LegacyLink external icon href="#">
  Link with external icon
</LegacyLink>
<Link href="#" external>
  Link with external icon
</Link>
Code Editor