Link

A Link navigates the user to another page, view or section, when the user clicks or taps on it.

Guidelines

When to use links

Use the Link component when you need to provide users with a clickable element to navigate to a different page, resource, or section in the same page.

Apart from links that navigate to other pages, there are the following different links:

• Links that open a modal instead of a new page (e.g. map links)
• Links that open a file instead of a web page (e.g. PDF or document links)
• Links that cause something to happen that the user would otherwise not expect (e.g. play a sound, like pronunciation links)
• Links that open a new website instead of just a new page (external links)^[1]
• Links that open a non-web protocol URI (e.g. mailto:, tel: links)

Several Wikimedia Movement projects provide extensive “manuals of style” for applying and designing for links, for example English Wikipedia.^[2]

Avoid using Link when the user needs to perform an action. In such cases, use Button instead. Learn more about the usage of links and buttons.

Specifications

1. Link text
   The text that describes the link destination as clearly as possible.
2. External link icon
   Indicates that the link will take the user to a different website. This icon cannot be replaced with other icons.

By default, the link text style is set to the base font in regular. However, it can be easily customized to other styles by applying any of the existing fonts, text sizes or formats defined in our font design tokens.

Component limitations

The length of link text can vary according to the context. While there's no strict character limit for links, it's advisable to keep them concise and descriptive as defined in the guidelines for writing copy.

Refer to the Link component in Codex Figma.

Types

1. Base links
   By default, links are only underlined when they are interacted with (hover, active).
2. Underlined links
   To suit user preferences and for accessibility reasons, links can always be underlined.
3. Red links (aka new links)
   Links to pages that do not exist yet. These display the color Red600 for both the normal or underlined types.^[3]

Interaction states

Links display accessible color variations that help clearly differentiate their interaction states:

Base link

Red link

1. Default
2. Hover
3. Active
4. Focus
5. Visited
6. Visited and hover

Links display the default browser outline on focus, which is equal to Blue600. The outline style varies in different browsers.
Links don't feature a disabled state. If you’re trying to convey an action, you might consider using a quiet button for that scenario instead.

Best practices

Consider the following recommendations when incorporating links into your designs to ensure consistency and effective usage.

Base link

Do:

• Use a Link when navigating to a different page, resource, or section in the same page.

Don't:

• Do not use links to perform actions. In that case, use a Button instead.

Red link

Do:

• Use a Red Link to represent that new pages without content can still be navigated to.

Don't:

• Do not use a Red Link to represent destructive actions. In such instances, use a destructive Button instead.

Content

The tone of a link should let a user know exactly where they will go when they select it. Link copy should be short and descriptive.

Base link

Base links signal to users the option to navigate to a different page, view, or resource.

Do:

• Highlight only the phrase that indicates the link destination. Translatable

Don't:

• Use the words click, tap or here. Avoiding these terms makes things clear and precise, whether the reader is using an assistive device, a mobile device or a desktop experience. Accessible

Red link

Red links are used to indicate that a page does not exist. Typically a red link is added to indicate that a page will be, or should be created soon.

Do:

• Create a title using appropriate naming conventions. Clear

Don't:

• Use special characters in the title. Clear

Keyboard navigation

Key	Function
Enter	If the Link is focused, it opens the Link.

References

1. English Wikipedia: External links
2. English Wikipedia: Manual of Style/Linking
3. English Wikipedia: Red link

Demos

Click on a link to see visited link styles.

Base link

The cat (Felis catus) is a domestic species of small carnivorous mammal.

NPM

<template>
	<p>
		The cat (Felis catus) is a <a class="cdx-docs-link" href="https://en.wikipedia.org/wiki/Species">domestic species</a>
		of small <a class="cdx-docs-link" href="https://en.wikipedia.org/wiki/Carnivore">carnivorous mammal</a>.
	</p>
</template>

<style lang="less">
// Note: you must import the design tokens before importing the link mixin
@import ( reference ) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';
@import ( reference ) '@wikimedia/codex/mixins/link.less';

.cdx-docs-link {
	.cdx-mixin-link();
}
</style>

MediaWiki

<template>
	<p>
		The cat (Felis catus) is a <a class="cdx-docs-link" href="https://en.wikipedia.org/wiki/Species">domestic species</a>
		of small <a class="cdx-docs-link" href="https://en.wikipedia.org/wiki/Carnivore">carnivorous mammal</a>.
	</p>
</template>

<style lang="less">
@import 'mediawiki.skin.variables.less';

.cdx-docs-link {
	.cdx-mixin-link();
}
</style>

Underlined link

As a predator, it is crepuscular, i.e. most active at dawn and dusk.

NPM

<template>
	<p>
		As a <a class="cdx-docs-link is-underlined" href="https://en.wikipedia.org/wiki/Predation">predator</a>,
		it is <a class="cdx-docs-link is-underlined" href="https://en.wikipedia.org/wiki/Crepuscular_animal">crepuscular</a>,
		i.e. most active at dawn and dusk.
	</p>
</template>

<style lang="less">
// Note: you must import the design tokens before importing the link mixin
@import ( reference ) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';
@import ( reference ) '@wikimedia/codex/mixins/link.less';

.cdx-docs-link {
	.cdx-mixin-link();
}
</style>

MediaWiki

<template>
	<p>
		As a <a class="cdx-docs-link is-underlined" href="https://en.wikipedia.org/wiki/Predation">predator</a>,
		it is <a class="cdx-docs-link is-underlined" href="https://en.wikipedia.org/wiki/Crepuscular_animal">crepuscular</a>,
		i.e. most active at dawn and dusk.
	</p>
</template>

<style lang="less">
@import 'mediawiki.skin.variables.less';

.cdx-docs-link {
	.cdx-mixin-link();
}
</style>

Link with icon

According to "Living with a Cat", cats are ready to go to new homes at about 12 weeks of age.

NPM

<template>
	<p>
		According to
		<a class="cdx-docs-link is-underlined" href="https://archive.org/details/completebookofca00behr/page/28/mode/2up">
			"Living with a Cat" <cdx-icon :icon="cdxIconLinkExternal" />
		</a>,
		cats are ready to go to new homes at about 12 weeks of age.
	</p>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxIcon } from '@wikimedia/codex';
import { cdxIconLinkExternal } from '@wikimedia/codex-icons';

export default {
	components: { CdxIcon },
	setup() {
		return {
			cdxIconLinkExternal
		};
	}
};
</script>

<style lang="less">
// Note: you must import the design tokens before importing the link mixin
@import ( reference ) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';
@import ( reference ) '@wikimedia/codex/mixins/link.less';

.cdx-docs-link {
	.cdx-mixin-link();

	// stylelint-disable-next-line selector-class-pattern
	.cdx-icon {
		color: inherit;
	}
}
</style>

MediaWiki

<template>
	<p>
		According to
		<a class="cdx-docs-link is-underlined" href="https://archive.org/details/completebookofca00behr/page/28/mode/2up">
			"Living with a Cat" <cdx-icon :icon="cdxIconLinkExternal"></cdx-icon>
		</a>,
		cats are ready to go to new homes at about 12 weeks of age.
	</p>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxIcon } = require( '@wikimedia/codex' );
const { cdxIconLinkExternal } = require( '@wikimedia/codex-icons' );

module.exports = defineComponent( {
	components: { CdxIcon },
	setup() {
		return {
			cdxIconLinkExternal
		};
	}
} );
</script>

<style lang="less">
@import 'mediawiki.skin.variables.less';

.cdx-docs-link {
	.cdx-mixin-link();

	// stylelint-disable-next-line selector-class-pattern
	.cdx-icon {
		color: inherit;
	}
}
</style>

Red link

Websites for cat lovers include The Catnip Times and Vanggy.

NPM

<template>
	<p>
		Websites for cat lovers include <a class="cdx-docs-link is-red-link" href="https://en.wikipedia.org/w/index.php?title=The_Catnip_Times">The Catnip Times</a>
		and <a class="cdx-docs-link is-red-link" href="https://en.wikipedia.org/w/index.php?title=Vanggy">Vanggy</a>.
	</p>
</template>

<style lang="less">
// Note: you must import the design tokens before importing the link mixin
@import ( reference ) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';
@import ( reference ) '@wikimedia/codex/mixins/link.less';

.cdx-docs-link {
	.cdx-mixin-link();
}
</style>

MediaWiki

<template>
	<p>
		Websites for cat lovers include <a class="cdx-docs-link is-red-link" href="https://en.wikipedia.org/w/index.php?title=The_Catnip_Times">The Catnip Times</a>
		and <a class="cdx-docs-link is-red-link" href="https://en.wikipedia.org/w/index.php?title=Vanggy">Vanggy</a>.
	</p>
</template>

<style lang="less">
@import 'mediawiki.skin.variables.less';

.cdx-docs-link {
	.cdx-mixin-link();
}
</style>

Less mixin usage

Less mixin

This component has been implemented as a Less mixin, not a Vue component. This mixin must be imported separately in your Less styles. See below for usage information.

WARNING

Before importing the Link mixin, you must first import the design tokens. If you don't, you will get errors that look like variable @color-progressive is undefined.

Default usage

To use base, underlined, and red link styles, apply the .cdx-mixin-link() mixin to a link class or to all anchor elements. This will automatically apply underline styles to links with the .is-underlined class, and red link styles to links with the .is-red-link class.

In ancient Egypt, cats were worshipped.

In ancient Egypt, cats were worshipped.

In ancient Egypt, cats were worshipped.

NPM

<template>
	<p>In <a class="cdx-docs-link" href="#">ancient Egypt</a>, cats were worshipped.</p>
	<p>In <a class="cdx-docs-link is-underlined" href="#">ancient Egypt</a>, cats were worshipped.</p>
	<p>In <a class="cdx-docs-link is-red-link" href="#">ancient Egypt</a>, cats were worshipped.</p>
</template>

<style lang="less">
// Note: you must import the design tokens before importing the link mixin
@import ( reference ) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';
@import ( reference ) '@wikimedia/codex/mixins/link.less';

.cdx-docs-link {
	.cdx-mixin-link();
}
</style>

MediaWiki

<template>
	<p>In <a class="cdx-docs-link" href="#">ancient Egypt</a>, cats were worshipped.</p>
	<p>In <a class="cdx-docs-link is-underlined" href="#">ancient Egypt</a>, cats were worshipped.</p>
	<p>In <a class="cdx-docs-link is-red-link" href="#">ancient Egypt</a>, cats were worshipped.</p>
</template>

<style lang="less">
@import 'mediawiki.skin.variables.less';

.cdx-docs-link {
	.cdx-mixin-link();
}
</style>

With custom CSS selectors

Alternately, you can apply sub-mixins directly to your own CSS selectors. The sub-mixins are:

• .cdx-mixin-link-base()
• .cdx-mixin-link-underlined()
• .cdx-mixin-link-red()

The domestic cat is a cosmopolitan species.

The domestic cat is a cosmopolitan species.

The domestic cat is a cosmopolitan species.

NPM

<template>
	<div class="cdx-docs-link-wrapper">
		<p>The domestic cat is a <a href="https://en.wikipedia.org/wiki/Cosmopolitan_distribution">cosmopolitan species</a>.</p>
		<p>The domestic cat is a <a class="cdx-docs-link-with-underline" href="https://en.wikipedia.org/wiki/Cosmopolitan_distribution">cosmopolitan species</a>.</p>
		<p>The domestic cat is a <a class="cdx-docs-red-link" href="https://en.wikipedia.org/wiki/Cosmopolitan_distribution">cosmopolitan species</a>.</p>
	</div>
</template>

<style lang="less">
// Note: you must import the design tokens before importing the link mixin
@import ( reference ) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';
@import ( reference ) '@wikimedia/codex/mixins/link.less';

.cdx-docs-link-wrapper {
	a {
		.cdx-mixin-link-base();
	}

	.cdx-docs-link-with-underline {
		.cdx-mixin-link-underlined();
	}

	.cdx-docs-red-link {
		.cdx-mixin-link-red();
	}
}
</style>

MediaWiki

<template>
	<div class="cdx-docs-link-wrapper">
		<p>The domestic cat is a <a href="https://en.wikipedia.org/wiki/Cosmopolitan_distribution">cosmopolitan species</a>.</p>
		<p>The domestic cat is a <a class="cdx-docs-link-with-underline" href="https://en.wikipedia.org/wiki/Cosmopolitan_distribution">cosmopolitan species</a>.</p>
		<p>The domestic cat is a <a class="cdx-docs-red-link" href="https://en.wikipedia.org/wiki/Cosmopolitan_distribution">cosmopolitan species</a>.</p>
	</div>
</template>

<style lang="less">
@import 'mediawiki.skin.variables.less';

.cdx-docs-link-wrapper {
	a {
		.cdx-mixin-link-base();
	}

	.cdx-docs-link-with-underline {
		.cdx-mixin-link-underlined();
	}

	.cdx-docs-red-link {
		.cdx-mixin-link-red();
	}
}
</style>