Skip to content
lib components / Navigation

Link

A link enables users to navigate to a different page, page section, or site.

ExamplesPropertiesGuidelines
import { Link } from "@siteimprove/fancylib";

If your link answers the question "What can I do?", instead of "Where can I go?", use the button component instead. Its href property enables it to behave like a link, but look like a button.

#Examples

The link component features various properties for adjusting its appearance. The following sections showcase these properties and explain when to use them.

#Default

Use the link's default appearance when it's presented by itself. That is, when it's not part of a sentence or a phrase. It features an arrow to indicate that it's a link without relying on color alone.

Medium standalone link (default)
<Link href="https://www.google.com">Medium standalone link (default)</Link>

#Size

Use this property to adjust how attention-grabbing a standalone link should be.

Small standalone link
Medium standalone link (default)
Large standalone link
<Link href="https://www.google.com" size="small"> Small standalone link </Link> <br /> <Link href="https://www.google.com" size="medium"> Medium standalone link (default) </Link> <br /> <Link href="https://www.google.com" size="large"> Large standalone link </Link> <br />

#Inline

Use this variant when the link is part of a sentence or a phrase. It features an underline, instead of an arrow, to indicate without color that it is a link. This variant inherits its size from the text it's part of.

This is an example of an inline link, which is part of a sentence.

<Paragraph> This is an example of an{" "} <Link href="https://www.google.com" inlineInText> inline link </Link> , which is part of a sentence. </Paragraph>

#Unstyled

Use this property when an interface element, such as an image, needs to behave like a link, but should not be styled like a standalone or inline link. Its custom styling and the UI context in which it's used should make clear that it's a link and where it links to.

some image with link
<Link href="https://www.google.com" unstyled> <img src={image} alt="some image with link" height="40" /> </Link>

#Open in new tab or window

When a link points to a page on another domain, it's generally best to open it in a new tab or window (depending on the user's browser setting). This can be achieved by setting the openNew property to true.

Opens in new tab:
Medium standalone link (default)
<Link href="https://www.google.com" openNew> Medium standalone link (default) </Link>

#Properties

Link
PropertyDescriptionDefinedValue
hrefRequired
stringUrl of the page the link redirects to
openNewOptional
booleanOpens the link in a new tab if set to true
childrenOptional
elementLabel for the link
onClickOptional
functionCallback for onClick events
inlineInTextOptional
booleanRenders the link inline if set to true, should be used when the link is part of a text block
unstyledOptional
booleanRenders the link without style if set to true
sizeOptional
"large" | "medium" | "small"Size of the link, defaults to `"medium"`
aria-labelOptional
stringScreen reader text for the link
disableWordBreakOptional
booleanWhen link is wrapped into single words
data-observe-keyOptional
stringUnique string, used by external script e.g. for event tracking
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)
tabIndexOptional
numberTab index of the outermost HTML element of the component
onKeyDownOptional
functionCallback for onKeyDown event
onMouseDownOptional
functionCallback for onMouseDown event
onMouseEnterOptional
functionCallback for onMouseEnter event
onMouseLeaveOptional
functionCallback for onMouseLeave event
onFocusOptional
functionCallback for onFocus event
onBlurOptional
functionCallback for onBlur event

#Guidelines

#Best practices

  • Use when the user needs to navigate to a different site, page, or page section.
  • Use the default variant when the link is presented by itself.
  • Use the inline variant when the link is part of a sentence or phrase.
  • Use the unstyled variant when an interface element, such as an image, needs to behave like a link, but should not be styled like a link (or button).

#Do not use when

  • The link needs to look like a button. Use the button component instead and configure its properties, so that it functions like a link. However, only do this if the button “feels” like a button to the user. It should answer the question “What can I do?”, not “Where can I go?”.
  • The user needs to toggle between different views. Use tabs or a toggle group instead.
  • The user needs to toggle between two opposing states with immediate effect. Use a toggle switch instead.

#Accessibility

  • Don't have two links to the same destination next to each other. For example: an icon with a link, and some text with the same link next to it.
  • Avoid generic link texts ("Click here", "Read more", "Learn more", etc.). The link should be able to stand on its own.

The component’s implementation ensures that it automatically follows these guidelines:

  • Pressing the Enter key executes the link and moves focus to the link target.
  • Add role=“link” to the element containing the link.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

  • Be descriptive and specific.,
  • Front-load the link text with relevant terms.
  • Tell users if the link takes you away from the platform (e.g. “You can learn more about HTTP status codes in our Help Center.” )
  • Refer to the page title in the text if the link is to a page (e.g. Integrations Overview instead of See an overview of your integrations).
  • Use markdown to insert links. It’s better for localization if we don’t concatenate strings.
  • Don't include closing punctuation unless the link is phrased as a question; in that case, close with a question mark (e.g. Forgot your password?)
  • Don't use a URL as link text (unless, of course, it's a broken link).