Newskit Logo
About

Link

Overview

A simple styled anchor element.

Usage

A link requires a href property to be passed in.

Theming

The default link component uses the following style tokens, which can be overridden:

Theme TokenContextual ColorColor Value
linkTextinteractivePrimary030
linkActiveinteractivePrimary050
linkHoverinteractivePrimary040
linkVisitedinteractiveVisited010

Props

Links have a number of props to facilitate a variety of uses. Any prop valid on an Anchor HTML element, is also valid on the Link component. Custom and required props are detailed below:

childrenstring
The content of the link is passed as the child of the component.
hrefstring
Passed to the href attribute of the rendered anchor element. The provided URL or fragment identifier will be loaded when the link is clicked.
eventContextobject
This props allows users to add extra event data to links' click events.
eventOriginatorstring = link
This props allows users to add event originator custom name. e.x.: 'newskit-link'.
externalboolean
This prop overrides the rendering of the "external" icon next to the Link body content. Whenever a Link component renders, it automatically checks if the passed href is external or internal to the website where the Link is used. If the href is external, an icon indicating this will be rendered to the right. In order to either stop this, or to force this to happen, pass this prop with a value of true or false.
overridesobject
If provided, overrides the respective presets for the component and provided elements.
stylePresetMQ<string>
If provided, this overrides the style preset applied to the Link.
typographyPresetMQ<string>
If provided, this overrides the typography preset applied to the Link.
spaceInlineMQ<string>
The "space" token refers to the spacing between child items. Only applicable if the Link children contains more than one element, or the external icon is rendered.
externalIconobject
sizestring
Allows you to override the default size of the External icon. The value of this prop has to be one of the icon size tokens. E.g: "iconSize030". For more tokens please refer to the /components/icons page.

Note: You can also set the icon size by passing it directly as a size prop to the icon, but by doing this you will override the iconSize passed from overrides. We discourage this approach but we will keep the functionality in case it is needed.
Refer to the defaults below for the object structure:
{
  stylePreset: "linkInline",
  spaceInline: "space010",
  externalIcon: {
    size: "iconSize010"
  }
}
For more information about how to apply overrides to a component please refer to the Override component defaults page.

Default HTML props

All the native HTML attributes which an anchor element can take, can also be passed. E.g: <Link aria-label='NewsKit staging website' href="http://newskit.staging-news.co.uk/">

Playground

Here you can play with the Link component and the LinkStandalone component.

LinkStandalone is an alternative export of the Link. All of the above applies to it, however the LinkStandalone uses a different default stylePreset which does not include the underline. Both the Link and LinkStandalone default stylePresets can be changed via the theme.

eventContext
external
import React from 'react';
import { Link } from 'newskit';

export default () => (
  <Link href="http://example.com">Some Link</Link>
);

For more information on overriding component defaults, see the docs here.

Rationale

Styling

Accessibility

Aria-label

By default there is no aria label set in the Link component and the text inside the anchor will be read by the Screen Reader But bear in mind that, if the text is not descriptive enough, an aria label will be necessary to understand where the link is taking the user to.

E.g:

<a href="..." aria-label="Films list of Harry Potter">Harry Potter<a/>

Underline styling

If the underline style is removed from a link, which has already a distinct color + underline combination, bear in mind some other indicator has to be added. This could be the case when overriding presets.

WCAG 2.0 has 2 additional requirements for body text links that are not underlined by default: The link text must have a 3:1 contrast ratio from the surrounding non-link text. The link must present a "non-color designator" (typically the introduction of the underline) on both mouse hover and keyboard focus. These two requirements help ensure that all users can differentiate links from non-link text, even if they have low vision, color deficiency, or have overridden page colors.

https://webaim.org/techniques/hypertext/link_text#underlining

Colour

Text and background colours must have a 3:1 minimum contrast ratio. Hover states should have clear contrast change or should include a non colour designator.

Button as link

In some circumstances, the Button component has the ability to behave as fully working and stylable link. All you need to do is pass a href property with valid url. Button links can be styled in the same way as a regular Button component.

Variations

Inline

These are used within paragraphs or sentences to link to different content on the same page or other pages. Our current link style is more akin to this.

Add a link inline style preset token (linkInline, linkInlineInverse) to the overrides.

Note: linkInline is the default Link token, so there is no need to pass it to the overrides.

Inline link

<Link href="/">Inline link</Link>
  
Inline link inverse

 <Link href="/" overrides={{stylePreset: 'linkInlineInverse'}}>
    Inline link inverse
  </Link>
  

External

An external link directs users to a page not produced by brand i.e. the website they currently are visiting. A trailing icon to depict the user is navigating away is often paired with the external link text.

Add a link inline style preset token (linkExternal, linkExternalInverse) to the overrides.

External link with external icon

<Link
  href="http://google.com/"
  overrides={{stylePreset: 'linkExternal'}}
>
  External link with external icon
</Link>
  
External link with external icon

<Link
  href="http://google.com/"
  overrides={{stylePreset: 'linkExternalInverse'}}
>
  External link inverse with external icon
</Link>
  

Standalone

Standalone links are used outside of body content, for example within navigational components such as menus, headers and footers.

Add a link standalone style preset token (linkStandalone, linkStandaloneInverse) to the overrides of the LinkStandalone component.

Note: linkStandalone is the default LinkStandalone token, so there is no need to pass it to the overrides.

Standalone link
Standalone link external

<LinkStandalone href="/">Standalone link</LinkStandalone>
<LinkStandalone href="https://google.com">Standalone link external</LinkStandalone>
  

<LinkStandalone
  href="/"
  overrides={{stylePreset: 'linkStandaloneInverse'}}
>
  Standalone link
</LinkStandalone>
<LinkStandalone
  href="https://google.com"
  overrides={{stylePreset: 'linkStandaloneInverse'}}
>
  Standalone link external
</LinkStandalone>