Learn Nuxt with a Collection of 100+ Tips!

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

pages/index.vue
<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.

pages/index.vue
<template>
  <NuxtLink :to="{ name: 'posts-id', params: { id: 123 } }">
    Post 123
  </NuxtLink>
</template>
Check out the Pages panel in Nuxt DevTools to see the route name and the params it might take.

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.

pages/index.vue
<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.

app.vue
<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 the Referer 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.

app.vue
<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

When not using external, <NuxtLink> supports all Vue Router's RouterLink props

  • href: An alias for to. If used with to, href will be ignored
  • noRel: If set to true, no rel attribute will be added to the link
  • external: Forces the link to be rendered as an a tag instead of a Vue Router RouterLink.
  • prefetch: When enabled will prefetch middleware, layouts and payloads (when using payloadExtraction) of links in the viewport. Used by the experimental crossOriginPrefetch config.
  • prefetchOn: Allows custom control of when to prefetch links. Possible options are interaction and visibility (default). You can also pass an object for full control, for example: { interaction: true, visibility: true }. This prop is only used when prefetch is enabled (default) and noPrefetch is not set.
  • noPrefetch: Disables prefetching.
  • prefetchedClass: A class to apply to links that have been prefetched.

Anchor

  • target: A target attribute value to apply on the link
  • rel: A rel attribute value to apply on the link. Defaults to "noopener noreferrer" for external links.
Defaults can be overwritten, see overwriting defaults if you want to change them.

Overwriting Defaults

In Nuxt Config

You can overwrite some <NuxtLink> defaults in your nuxt.config

These options will likely be moved elsewhere in the future, such as into app.config or into the app/ directory.
nuxt.config.ts
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'
      }
    }
  }
})

You can overwrite <NuxtLink> defaults by creating your own link component using defineNuxtLink.

components/MyNuxtLink.ts
export default defineNuxtLink({
  componentName: 'MyNuxtLink',
  /* see signature below for more */
})

You can then use <MyNuxtLink /> component as usual with your new defaults.

interface NuxtLinkOptions {
  componentName?: string;
  externalRelAttribute?: string;
  activeClass?: string;
  exactActiveClass?: string;
  trailingSlash?: 'append' | 'remove'
  prefetch?: boolean
  prefetchedClass?: string
  prefetchOn?: Partial<{
    visibility: boolean
    interaction: boolean
  }>
}
function defineNuxtLink(options: NuxtLinkOptions): Component {}
  • componentName: A name for the component. Default is NuxtLink.
  • externalRelAttribute: A default rel attribute value applied on external links. Defaults to "noopener noreferrer". Set it to "" to disable
  • activeClass: A default class to apply on active links. Works the same as Vue Router's linkActiveClass 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's linkExactActiveClass option. Defaults to Vue Router's default ("router-link-exact-active")
  • trailingSlash: An option to either add or remove trailing slashes in the href. If unset or not matching the valid values append or remove, it will be ignored.
  • prefetch: Whether or not to prefetch links by default.
  • prefetchOn: Granular control of which prefetch strategies to apply by default.
  • prefetchedClass: A default class to apply to links that have been prefetched.
Read and edit a live example in Docs > Examples > Routing > Pages.