<NuxtLink>
Nuxt provides <NuxtLink> component to handle any kind of links within your application.
<NuxtLink>
is a drop-in replacement for both Vue Router's <RouterLink>
component and HTML's <a>
tag. It intelligently determines whether the link is internal or external and renders it accordingly with available optimizations (prefetching, default attributes, etc.)Internal Routing
In this example, we use <NuxtLink>
component to link to another page of the application.
<template>
<NuxtLink to="/about">
About page
</NuxtLink>
<!-- <a href="/about">...</a> (+Vue Router & prefetching) -->
</template>
Passing Params to Dynamic Routes
In this example, we pass the id
param to link to the route ~/pages/posts/[id].vue
.
<template>
<NuxtLink :to="{ name: 'posts-id', params: { id: 123 } }">
Post 123
</NuxtLink>
</template>
Handling 404s
When using <NuxtLink>
for /public
directory files or when pointing to a different app on the same domain, you should use the external
prop.
Using external
forces the link to be rendered as an a
tag instead of a Vue Router RouterLink
.
<template>
<NuxtLink to="/the-important-report.pdf" external>
Download Report
</NuxtLink>
<!-- <a href="/the-important-report.pdf"></a> -->
</template>
The external logic is applied by default when using absolute URLs and when providing a target
prop.
External Routing
In this example, we use <NuxtLink>
component to link to a website.
<template>
<NuxtLink to="https://nuxtjs.org">
Nuxt website
</NuxtLink>
<!-- <a href="https://nuxtjs.org" rel="noopener noreferrer">...</a> -->
</template>
target
and rel
Attributes
A rel
attribute of noopener noreferrer
is applied by default to absolute links and links that open in new tabs.
noopener
solves a security bug in older browsers.noreferrer
improves privacy for your users by not sending theReferer
header to the linked site.
These defaults have no negative impact on SEO and are considered best practice.
When you need to overwrite this behavior you can use the rel
and noRel
props.
<template>
<NuxtLink to="https://twitter.com/nuxt_js" target="_blank">
Nuxt Twitter
</NuxtLink>
<!-- <a href="https://twitter.com/nuxt_js" target="_blank" rel="noopener noreferrer">...</a> -->
<NuxtLink to="https://discord.nuxtjs.org" target="_blank" rel="noopener">
Nuxt Discord
</NuxtLink>
<!-- <a href="https://discord.nuxtjs.org" target="_blank" rel="noopener">...</a> -->
<NuxtLink to="https://github.com/nuxt" no-rel>
Nuxt GitHub
</NuxtLink>
<!-- <a href="https://github.com/nuxt">...</a> -->
<NuxtLink to="/contact" target="_blank">
Contact page opens in another tab
</NuxtLink>
<!-- <a href="/contact" target="_blank" rel="noopener noreferrer">...</a> -->
</template>
Props
RouterLink
When not using external
, <NuxtLink>
supports all Vue Router's RouterLink
props
to
: Any URL or a route location object from Vue Routercustom
: Whether<NuxtLink>
should wrap its content in an<a>
element. It allows taking full control of how a link is rendered and how navigation works when it is clicked. Works the same as Vue Router'scustom
propexactActiveClass
: A class to apply on exact active links. Works the same as Vue Router'sexact-active-class
prop on internal links. Defaults to Vue Router's default"router-link-exact-active"
)replace
: Works the same as Vue Router'sreplace
prop on internal linksariaCurrentValue
: Anaria-current
attribute value to apply on exact active links. Works the same as Vue Router'saria-current-value
prop on internal linksactiveClass
: A class to apply on active links. Works the same as Vue Router'sactive-class
prop on internal links. Defaults to Vue Router's default ("router-link-active"
)
NuxtLink
href
: An alias forto
. If used withto
,href
will be ignorednoRel
: If set totrue
, norel
attribute will be added to the linkexternal
: Forces the link to be rendered as ana
tag instead of a Vue RouterRouterLink
.prefetch
: When enabled will prefetch middleware, layouts and payloads (when using payloadExtraction) of links in the viewport. Used by the experimental crossOriginPrefetch config.noPrefetch
: Disables prefetching.prefetchedClass
: A class to apply to links that have been prefetched.
Anchor
target
: Atarget
attribute value to apply on the linkrel
: Arel
attribute value to apply on the link. Defaults to"noopener noreferrer"
for external links.
Overwriting Defaults
In Nuxt Config
You can overwrite some <NuxtLink>
defaults in your nuxt.config
app.config
or into the app/
directory.export default defineNuxtConfig({
experimental: {
defaults: {
nuxtLink: {
// default values
componentName: 'NuxtLink',
externalRelAttribute: 'noopener noreferrer',
activeClass: 'router-link-active',
exactActiveClass: 'router-link-exact-active',
prefetchedClass: undefined, // can be any valid string class name
trailingSlash: undefined // can be 'append' or 'remove'
}
}
}
})
Custom Link Component
You can overwrite <NuxtLink>
defaults by creating your own link component using defineNuxtLink
.
export default defineNuxtLink({
componentName: 'MyNuxtLink',
/* see signature below for more */
})
You can then use <MyNuxtLink />
component as usual with your new defaults.
defineNuxtLink
Signature
interface NuxtLinkOptions {
componentName?: string;
externalRelAttribute?: string;
activeClass?: string;
exactActiveClass?: string;
prefetchedClass?: string;
trailingSlash?: 'append' | 'remove'
}
function defineNuxtLink(options: NuxtLinkOptions): Component {}
componentName
: A name for the component. Default isNuxtLink
.externalRelAttribute
: A defaultrel
attribute value applied on external links. Defaults to"noopener noreferrer"
. Set it to""
to disableactiveClass
: A default class to apply on active links. Works the same as Vue Router'slinkActiveClass
option. Defaults to Vue Router's default ("router-link-active"
)exactActiveClass
: A default class to apply on exact active links. Works the same as Vue Router'slinkExactActiveClass
option. Defaults to Vue Router's default ("router-link-exact-active"
)prefetchedClass
: A default class to apply to links that have been prefetched.trailingSlash
: An option to either add or remove trailing slashes in thehref
. If unset or not matching the valid valuesappend
orremove
, it will be ignored.