Skip to content
lib components / Navigation

Link

A link enables users to navigate to a different page, page section, or resource (like a downloadable file).

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

Links provide a way for users to move between different parts of the application or access external resources. They should be used to enhance navigation and provide access to relevant information.

Need to change the style of a link? You can easily customize the appearance of links using the properties described in the following sections.

#Basic usage

Use the default variation for standalone links, providing a clear visual indication of interactivity. It features an arrow to indicate that it's a link without relying on color alone, ensuring proper communication to color-blind users.

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 within sentences or paragraphs, maintaining the flow of text while providing clear navigation. 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. To avoid localization problems, do not use a placeholder for the link text.

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 for interface elements that need to behave like a link without the standard link styling. 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>

#Download linked resource

When a link leads to a resource intended to be downloaded rather than displayed in the browser the download property can be set to true. Provide a string value to specify the default file name like so: download="filename.pdf". Best practice is to not open a link, intendded to be downloaded, in a new tab, so avoid using openNew and download together.

#Link container and Link text

If you want some of the content to not have the link text styling but still be part of the link.

Opens in new tab:

Pre:

Styled link text
<LinkContainer href="https://www.google.com" openNew> <Badge>Pre:</Badge> <LinkContainer.LinkText>Styled link text</LinkContainer.LinkText> </LinkContainer>

#Properties

Link
PropertyDescriptionDefinedValue
hrefRequired
stringUrl of the page the link redirects to
openNewOptional
booleanOpens the link in a new tab if set to true
downloadOptional
| unknownDownloads the linked resource (instead of displaying it in the browser) if set to true. Provide a string to specify the default file name.
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
aria-labelOptional
stringScreen reader text for the link
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
unstyledOptional
booleanRenders the link without style if set to true
sizeOptional
"large" | "medium" | "small"Size of the link, defaults to `"medium"`
disableWordBreakOptional
booleanWhen link is wrapped into single words

#Guidelines

#Best practices

  • Purpose: Use links for navigation within the application, to external resources, to downloadable files, or to provide contact information.
  • Variants:
    • Use the default variant for standalone links that are presented by themselves.
    • Use the inline variant for links within sentences or paragraphs.
    • Use the unstyled variant when interface elements, like images, need to function as links but should not be styled like a typical link.
  • Visual clarity:
    • Distinguish links: Links have underlines added automatically to distinguish them from surrounding text. Ensure sufficient color contrast is used, especially when links are near other interactive elements.
    • Interactive feedback: The :focus and :active states are automatically applied to links to provide visual feedback for keyboard and mouse users.
    • Visited states: Use a distinct visual style for visited links to help users recognize previously accessed pages.
  • Meaningful labels:
    • Use concise, descriptive link text that clearly communicates the link's purpose or destination.
    • Avoid generic link text like "click here" or "learn more".
    • When linking to downloads, specify the file type and size.
  • Context: Provide sufficient context so users understand where the link leads or what action it performs.

#Do not use when

  • The link needs to perform an action: Use buttons for actions like "Submit," "Download," "Cancel," or other interactive elements that trigger functionality within the current page. Links are primarily for navigation.
  • The user needs to toggle between different views or states: Use tabs, content switcher, or toggle switches for these interactions, as they provide clearer visual cues and affordances for those actions.
  • Repeating links: Avoid excessive or unnecessary links on a page or within a section of text, especially if they lead to the same destination. This can clutter the interface and make it harder for users to find relevant information.
  • Linking to page titles/urls from a table: If you need to display a title and and URL of a page in a table for example, please use Title Url.
  • The link needs to look like a button: If the visual style of a button is required, use the button component and configure its properties to function as a link. However, only do this when the primary purpose is to navigate to a new location ("Where can I go?"), not to perform an action ("What can I do?").

#Accessibility

  • Color contrast: Ensure sufficient color contrast between link text and surrounding text.
  • Descriptive text: Use link text that clearly describes the destination. Avoid generic phrases like "click here" or "learn more".
  • aria-label: Provide an aria-label for links with icons or images to provide a text alternative for screen readers.
  • Keyboard navigation: Ensure links are easily navigable using the keyboard (using the Tab key).
  • New windows:
    • Open links in a new window or tab only when necessary (e.g., for external websites, downloads, or to avoid interrupting a workflow).
    • Use the Open new tab or window variant to open links in a new tab and inform users by adding "(opens in new tab)" after the link text.
    • Alternatively, for complex situations, consider using a Tooltip with the text "Opens in new tab" alongside an icon-only button to indicate that the link will open in a new window. This approach can provide a more noticeable cue for users.
  • Minimum size: Make link text easily clickable with a font size of at least 12px. Interactive elements should be at least 24×24 pixels in size, or have 24px of spacing around them for better usability on touch devices.

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

  • Clarity:
    • Use clear and concise language that accurately describes the link's purpose or destination.
    • Avoid ambiguity or jargon.
  • Specificity:
    • Clear destinations: Use link text that clearly indicates the link's destination.
    • Page titles as links: When linking to a page within the application, use the page title as the link text (e.g., "Integrations Overview" instead of "See an overview of your integrations").
    • Link specific words:
      • In sentences: Link only the key words needed to understand the destination. Avoid linking entire sentences. For example, instead of "Click here to read the documentation", use "Read the documentation".
      • For standalone links: Link the whole phrase, such as "Download the report".
    • Front-load keywords: Place the most important information at the beginning of the link text.
    • External links: Clearly indicate when a link leads to an external website (e.g., "You can learn more about HTTP status codes in our Help Center.").
    • Sentence case: Use sentence case for link text.
    • Punctuation: Avoid punctuation in link text, except for question marks when phrasing a link as a question (e.g., "Forgot your password?").
    • No URLs as labels: Don't use a URL as link text, unless it's a broken link that needs to be displayed. If showing a link in a table, use Title Url.