Link element

Links are used to help users navigate to new sections, pages or websites. Links have default, hover and selected states which provide visual cues to help the user interact with them or identify visited pages.

github location npm version


The label of a link should describe clearly the destination of the link. It should make sense to the user with little or no need to check other elements for context. Avoid non descriptive labels such as “click here” and “read more”.

Consider a user who scans through the content or uses a screen reader, how much information can they get from the link’s description alone? Use this principle as a guideline to create more descriptive links.

Avoid opening links in a new tab or window. It can be disorienting and can cause accessibility issues for people who cannot visually perceive that the new tab has opened.

When to use

Links should be used to help a user navigate to pages, sections or external websites.

When not to use

Links should not be used to initiate actions, change or manipulate data. Use vf-button instead for such actions.

Related documentation

For more information on links please consult the following documents:


This component targets WCAG 2.1 AA accessibility.


Nunjucks syntax

Depending on your environment you'll want to use render or include. As a rule of thumb: server-side use include, precompiled browser use render. If you're using vf-eleventy you should use include.

Using include

You'll need to pass a context object from your code or Yaml file (example), as well as the path to the Nunjucks template. Nunjucks' include is an abstraction of render and provides some additional portability.

{% set context fromYourYamlFile %}
- or -
{% set context = { 
"component-type" : "element",
"link_href" : "JavaScript:Void(0);",
"buttonType" : "default",
"text" : "A default link",
{% include "../path_to/vf-link/vf-link.njk" %}

Using render

This approach is best for bare-bones Nunjucks environments, such as precompiled templates with the Nunjucks slim runtime where include is not be available.

{% render '@vf-link', {
  "component-type" : "element",
  "link_href" : "JavaScript:Void(0);",
  "buttonType" : "default",
  "text" : "A default link",}
 <a href="JavaScript:Void(0);" class="vf-link">A default link</a>


Installation info

This component is distributed with npm. After installing npm, you can install the vf-link with this command.

$ yarn add --dev @visual-framework/vf-link


The source files included are written in Sass(scss). You can point your Sass include-path at your node_modules directory and import it like this.

@import "@visual-framework/vf-link/index.scss";

Make sure you import Sass requirements along with the modules. You can use a project boilerplate or the vf-sass-starter




  • Fixed: Fixed space issue to make the 'default' variant example look like a link (#1895)
  • Added: Added documentation for vf-link: description in About, Usage notes and links to related documentation.(#1894)
  • Added: Added accessibility note to vf-link documentation (#1899)


  • removes secondary link colours, as this is more often defined by the parent component.
  • removes the 'dark mode' styles as these are not being used.


  • changes any set- style functions to cleaner version


  • Improves default link colours


  • Removes underline on default
  • Improves demonstration
  • Adds vf-u-background-color--grey--dark


  • Initial stable release


File system location: components/vf-link

Find an issue on this page? Propose a change or discuss it.