Link

A link is a navigational element that takes a user to another URL, an element within a page, or a file.

Examples

Loading story...
TODO:
Add examples for all link variants. Create an issue

View in Pajamas UI Kit →

Structure

Numbered diagram of a link structure
Link structure
  1. Text: Specifies or references the link's destination.
  2. Icon (optional): Indicates the destination is on an external domain.

Guidelines

When to use

  • A link (anchor <a>) element is used as navigation to:
    • A new URL.
    • An element within a page.
    • A file.

When not to use

  • If you are performing an action, like saving, consider using a button element instead.

Categories

There are four categories of links in GitLab. Although all links are navigational, those that persist from page to page and guide users through the application – such as those within the navigation sidebar, breadcrumbs, and pagination – are described separately, and not included as part of the link component.

  1. Inline text link: Link that appears within body text, like a paragraph or sentence. In order to distinguish a linked reference from surrounding content, a link within body copy must be underlined. Inline text links can be user-generated, for example, referencing an issue with "#3126" in the markdown editor of a merge request description where the link's primary function is linking to the referred issue. They can also be in text generated from a source file, for example, a "learn more about pipelines" link in the paragraph of an empty state template.
  2. User interface (UI) link: Standalone link in the UI. User interface links are not user-generated. For example, a link in the system notes that compares the changes in a new commit to a previous one. The placement, color, and actionable text all provide link affordance. A link button has a similar style, but is used for an action and not a link.
  3. Meta link: Standalone text or text within a short string of system-generated content may contain multiple meta links. Meta links share a meaningful datapoint or reference, and are only links secondarily. For example, the primary function of including "%15.8" in a string is to communicate the milestone, though it can also link to more information about it.
  4. Mention: Indicates when a user is "@" mentioned in the content. The username links to the user's profile. A mention link can be within body or meta content.

Appearance

  • An inline text link should always be underlined to distinguish it from surrounding text, regardless of formatting applied (bold, italic, or monospace) or parent text element (heading, paragraph, list, or code).
  • A UI link has no underline at rest, but is underlined for hover, focus, and active states.
  • Meta links represent a wide variety of content and their style adapts for each context. Meta links don't have an underline at rest, but are underlined for hover, focus, and active states. Similar to inline links, they appear this way regardless of formatting applied (bold, italic, monospace). Because of the available styling, which can appear similar to unlinked text, it's critical to ensure that users understand what is linked and what isn't in each context. Additionally, similar types of linked meta content should be styled the same throughout the product.
  • A mention link has a background color that depends on whether it's for the current user or another user. When embedded in body text and on hover the text is underlined.
  • Although a UI or meta link can have a style similar to a link button, select the correct component based on meaning rather than by appearance alone. See When to use above.
  • All links have a visible focus state. See Accessibility notes below.

Behavior

  • A link opens the destination in the same window by default. By doing so a user can still choose to open the link in a new tab or window, whereas using target="_blank" removes all other methods.
  • A link can use target="_blank" if it's intentional that the user cannot use the browser's back function to return to the reference, and that it's clear to the user they are leaving the current experience.
  • Native controls to open a link in a new tab or window aren't suppressed.
  • Text truncation guidelines also apply to links.

Content

  • A user should be able to predict where they will go upon click.
  • Avoid vague text such as "click here," URLs as link text, or creating a link from more than just a short sentence. Link texts should be clear and meaningful. For example, Before reviewing a MR, review the best practices.
  • If a link is at the end of a sentence, the period should not be part of the link.
  • An external link should use the external link icon. The icon should use aria-label="(external link)", or similar, to communicate the purpose to screen reader users. For example, Learn more about Kubernetes .

Accessibility

For all links:

For inline text links:

  • Color can't be the only way to visually distinguish a link. The link color doesn't have at least a 3:1 contrast ratio from surrounding text, therefore, an underline is used for all states as a visual means to indicate it. See Understanding WCAG SC 1.4.1 Use of Color.
  • Since an underline is used as a required graphical element to distinguish a link, it must have at least a 3:1 contrast ratio against the background color for all states. See Understanding WCAG SC 1.4.11 Non-text Contrast.

For user interface links:

  • The placement and text of a link should identify itself as such in a predictable way.
  • An underline is not required at rest, but present for hover.
  • Consecutive interface links should have sufficient space between them so that they appear as separate elements and not one continuous sentence or link.

For meta links:

  • As mentioned in the categories section, the main purpose of a meta link is first and foremost as content. It's not necessary for the text to be linked, but it is so that a user could get more information if desired. Therefore, the visual emphasis that would come from an underline is not used, even if the link is within a string of unlinked text. An underline is present on hover. This is an intentional decision to visually simplify certain sections in the UI that contain multiple meta links and may change in the future. More discussion and consideration can be found this issue.

For mention links:

  • When the link is within body copy, follow the above guides for inline text links. The background color and/or @ prefix don't qualify for sufficient contrast or visual distinction in this context.
  • When the link is used as meta information, that is, first and foremost as content where linking to a user isn't necessary or consequential, then follow the above guides for meta links.

Last updated at: