NewsKit Mobile Logo

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'.
noUnderlineboolean
If provided, determines if the link will be underlined.
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.

Props
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.