Skip to main content

TextLink
ready
Storybook

The TextLink component renders an anchor tag <a> that takes users to another page, external or internal to Grafana.

Loading...
Live Editor
<TextLink href="https://google.com" external>
  Go to Google
</TextLink>

Usage​

When to use​

  • To redirect the user to another page, external or internal.
  • When redirecting the user through a link in a word or phrase within a paragraph.
  • When redirecting the user through a link in a word or phrase, not within a paragraph but surrounded by other blocks of text.

When not to use​

  • When its purpose is to trigger an action, please use a Button or IconButton component.
  • When it still redirects the user, but it should have the same appearance as a button, please use the LinkButton component.
  • When the link is solely comprised of an icon, use the IconButton component.

Do’s​

  • Use the default styles as the first and main option as they are designed to be accessible and consistent.
  • Use the external icon (the default one) when the TextLink directs to an external page as its meaning is broadly known.
  • In the instance the default icon does not fit, please use one of the icons from our library.

Don’ts​

  • Do not use the ‘primary’ color in a standalone link unless it is a special use case such as the ‘Dashboard list’, menu items or similar.
  • Do not override any styles in any way. Instead, ask the Design System team for an improvement of this component.
  • Do not attempt to add a new icon. You should follow a contribution path to first add the icon to our Design System and then use it in this component.

Content​

  • The TextLink component mainly contains text and, optionally, an icon.
  • Make link text abundantly clear as to what the subsequent page is about.
  • Avoid using phrases such as Click here, More, and Read more unless they are within a card component or similar. Do not use them as standalone link text, as they can be confusing when a screen reader reads them out of context.
  • Aim for a maximum of two links per paragraph.
  • Keep link text short and concise.
  • Never start with articles: a, an, or the.
  • Avoid linking whole sentences; aim for a maximum of four to five words.

Types​

Within Grafana, there are two different types of text links: inline or standalone. They can either be wrapped by text or serve as a standalone element.

TypesPurpose
InlineIt is part of a broader text. It will be surrounded by text, before, after or in both directions. Although it can show an icon at its end, we advise not to do that
StandaloneIt is a block not surrounded immediately by more text

Subtypes​

Both inline and standalone text links will redirect the user to a specific page. Therefore, depending on their function, they can be either internal or external.

SubtypesPurpose
InternalRedirect the user to a page inside Grafana
ExternalRedirect the user to a page outside Grafana. The page will open a new window as we use target="_blank" and rel="noreferrer" to ensure that it is a safe cross-origin destination link. By default, an external text link will show the external-link-alt icon

Formatting​

Anatomy​

  • Text: The link's text informs the user where they will be directed.
  • Icon: The icon provides context about the destination. For example, by default, an external link will display the ‘external-link-alt’ icon. If the link leads to another part of the same page, the icon might be ‘anchor’.

Placement​

  • Inline: (default) The inline text link will follow the alignment of the text wrapped around it.
  • Standalone: This type of text link requires a parent element / container in which to set the appropriate display value.

Behaviour​

The following is the default behaviour and will be applied according to its type.

  1. Inline:

    Default: Blue and underlined. The user will be able to change this value through the color prop, but the rest will remain the same.

    On hover: Blue and not underlined.

  2. Standalone:

    Default: Blue and not underlined.

    On hover: Blue and underlined.

Spacing​

  • Between text and icon: the gap is set to 0.5em, so it will adapt itself to the change of the font size
  • The text itself: there is no margin or padding applied
  • Between the block text and the text link the space is not modified, so will be the same as the existing between the words of the paragraph.

Accessibility​

  • The text that contains the link should be informative
  • The aria-describedby attribute can be used to provide extra text for a screen reader besides the link text.
  • Assistive technology may consider an ARIA label to replace the link text, so if there is a need for more context please use aria-describedby.

Further Reading & Sources​

Playground​