Link

A link allows a user to navigate to a different location.

View sourceView on npmReport an issueWAI-ARIA

Links are used as navigational elements and can be used on their own or inline with text. They provide a lightweight option for navigation but like other interactive elements, too many links will clutter a page and make it difficult for users to identify their next steps. This is especially true for inline links, which should be used sparingly.

Anatomy

Structure

<Link>
    <Icon /> /* (Optional) An icon in the link */
    <Text /> /* (Optional) The text content of the link */
</Link>

Composed Components

A Link uses the following components:

Icon

An icon component is used to render a custom icon.

Text

A text component is a primitive component matching Hopper's typography type scale.

Usage

Disabled

Links can be disabled.

External

An external text link will render by default with rel="noopener noreferrer" and target="_blank" attributes.

No Href

When a <Link> does not have an href prop, it is rendered as a <span role="link"> instead of an <a>. Events will need to be handled in JavaScript with the onPress prop.

Note: this will not behave like a native link. Browser features like context menus and open in a new tab will not apply.

Variants

Links can be presented in different variants.

Sizes

Links can be presented in different sizes.

Inherit Size

The size can also be inherited.

Icon

Links can contain an icon.

Start Icon

Non standard start icons can be provided to handle special cases. However, think twice before adding start icons, end icons should be your go to.

Icon Only

A link's content can be a single icon. When using this variant, an accessible name must be provided through the aria-label prop. See WCAG practices.

Quiet

All links can have a quiet style, without an underline. This style should only be used when the placement and context of the link is explicit enough that a visible underline isn't necessary.

Standalone

All links can have a standalone style, without an underline which is similar to quiet, the difference is this adds block padding to make it more similar to a button.

React Router Link

A button can be rendered as a react router link when using the href property and setting the navigate property on the HopperProvider

Custom Styles

When the colors from the variant props are not enough, you can use the color prop to set the color of the link. This removes the hover and focus colors from the link. Use the color props when a link needs to be placed on top of a colored background or visual. Make sure that the background and the link color meet the minimum color contrast ratio.

Image

A link's content can be an image element.

Best Practices

Links are used primarily for navigation, and usually appear within or directly following a sentence. Buttons are used primarily for actions. Differentiating between the two both in the design and code result in:

  • A more inclusive experience for assistive technology users.
  • A more cohesive visual experience for sighted users.
  • Products that are easier to maintain at scale.

Open new tabs only when necessary

Use links whenever possible to avoid disorienting users and causing accessibility problems by opening a new tab. When using an external link, always use the NewTab icon beside the link's label. External links should be used when users are:

  • Performing a task or workflow.
  • Navigating to a page outside of the Workleap platform.

Use links when you want users to:

  • Navigate to a different page within the application
  • Navigation to an entirely different site
  • Jump to an element on the same page
  • Link to emails or phone numbers

Use a button instead of a link for actions that will change data or manipulate how it is displayed, change a state, or trigger an action. Buttons should never be used for navigational actions.

Props

variant?

The visual style of the link.

Defaults to primary.
size?

Size of the link.

Defaults to inherit.
isQuiet?

Whether the link should be displayed with a quiet style.

isExternal?

Whether the link should open in a new tab.

isStandalone?

Wheter the link is standalone

style?

The inline style for the element. A function may be provided to compute the style based on component state.

isDisabled?

Whether the link is disabled.

autoFocus?

Whether the element should receive focus on render.

href?

A URL to link to. See MDN.

hrefLang?

Hints at the human language of the linked URL. SeeMDN.

target?

The target window for the link. See MDN.

rel?

The relationship between the linked resource and the current page. See MDN.

download?

Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.

ping?

A space-separated list of URLs to ping when the link is followed. See MDN.

referrerPolicy?

How much of the referrer to send when following the link. See MDN.

routerOptions?

Options for the configured client side router.

children?

The children of the component. A function may be provided to alter the children based on component state.

className?

The CSS className for the element. A function may be provided to compute the class based on component state.

Migration Notes

Coming from Orbiter, you should be aware of the following changes:

  • Link, IconLink and TextLink have all been merged into one.
  • LinkAsButton has been removed. It is now possible to use the Link component without an href attribute.