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

[app/pages/index.vue]

<template>
  <NuxtLink to="/about">About page</NuxtLink>
</template>

Passing Params to Dynamic Routes

In this example, we pass the id param to link to the route ~/pages/posts/[id].vue.

[app/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.

When you pass an object into the to prop, <NuxtLink> will inherit Vue Router’s handling of query parameters. Keys and values will be automatically encoded, so you don’t need to call encodeURI or encodeURIComponent manually.

Handling Static File and Cross-App Links

By default, <NuxtLink> uses Vue Router’s client side navigation for relative route. When linking to static files in the /public directory or to another application hosted on the same domain, it might result in unexpected 404 errors because they are not part of the client routes. In such cases, you can use the external prop with <NuxtLink> to bypass Vue Router’s internal routing mechanism.

The external prop explicitly indicates that the link is external. <NuxtLink> will render the link as a standard HTML <a> tag. This ensures the link behaves correctly, bypassing Vue Router’s logic and directly pointing to the resource.

Linking to Static Files

For static files in the /public directory, such as PDFs or images, use the external prop to ensure the link resolves correctly.

[app/pages/index.vue]

<template>
  <NuxtLink
    to="/example-report.pdf"
    external
  >
    Download Report
  </NuxtLink>
</template>

Linking to a Cross-App URL

When pointing to a different application on the same domain, using the external prop ensures the correct behavior.

[app/pages/index.vue]

<template>
  <NuxtLink
    to="/another-app"
    external
  >
    Go to Another App
  </NuxtLink>
</template>

Using the external prop or relying on automatic handling ensures proper navigation, avoids unexpected routing issues, and improves compatibility with static resources or cross-application scenarios.

External Routing

In this example, we use <NuxtLink> component to link to a website.

[app/app.vue]

<template>
  <NuxtLink to="https://nuxtjs.org">
    Nuxt website
  </NuxtLink>
  <!-- <a href="https://nuxtjs.org" rel="noopener noreferrer">...</a> -->
</template>

rel and noRel Attributes

A rel attribute of noopener noreferrer is applied by default to links with a target attribute or to absolute links (e.g., links starting with http://, https://, or //).

• 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 or noRel props.

[app/app.vue]

<template>
  <NuxtLink to="https://twitter.com/nuxt_js">
    Nuxt Twitter
  </NuxtLink>
  <!-- <a href="https://twitter.com/nuxt_js" rel="noopener noreferrer">...</a> -->

  <NuxtLink
    to="https://discord.nuxtjs.org"
    rel="noopener"
  >
    Nuxt Discord
  </NuxtLink>
  <!-- <a href="https://discord.nuxtjs.org" rel="noopener">...</a> -->

  <NuxtLink
    to="/about"
    target="_blank"
  >About page</NuxtLink>
  <!-- <a href="/about" target="_blank" rel="noopener noreferrer">...</a> -->
</template>

A noRel prop can be used to prevent the default rel attribute from being added to the absolute links.

[app/app.vue]

<template>
  <NuxtLink
    to="https://github.com/nuxt"
    no-rel
  >
    Nuxt GitHub
  </NuxtLink>
  <!-- <a href="https://github.com/nuxt">...</a> -->
</template>

noRel and rel cannot be used together. rel will be ignored.

Prefetch Links

Nuxt automatically includes smart prefetching. That means it detects when a link is visible (by default), either in the viewport or when scrolling and prefetches the JavaScript for those pages so that they are ready when the user clicks the link. Nuxt only loads the resources when the browser isn’t busy and skips prefetching if your connection is offline or if you only have 2g connection.

[app/pages/index.vue]

<NuxtLink to="/about" no-prefetch>
About page not pre-fetched
</NuxtLink>

<NuxtLink to="/about" :prefetch="false">
About page not pre-fetched
</NuxtLink>

Custom Prefetch Triggers

We now support custom prefetch triggers for <NuxtLink> after v3.13.0. You can use the prefetchOn prop to control when to prefetch links.

<template>
  <NuxtLink prefetch-on="visibility">
    This will prefetch when it becomes visible (default)
  </NuxtLink>

  <NuxtLink prefetch-on="interaction">
    This will prefetch when hovered or when it gains focus
  </NuxtLink>
</template>

• visibility: Prefetches when the link becomes visible in the viewport. Monitors the element’s intersection with the viewport using the Intersection Observer API. Prefetching is triggered when the element is scrolled into view.
• interaction: Prefetches when the link is hovered or focused. This approach listens for pointerenter and focus events, proactively prefetching resources when the user indicates intent to interact.

You can also use an object to configure prefetchOn:

<template>
  <NuxtLink :prefetch-on="{ interaction: true }">
    This will prefetch when hovered or when it gains focus
  </NuxtLink>
</template>

Enable Cross-origin Prefetch

To enable cross-origin prefetching, you can set the crossOriginPrefetch option in your nuxt.config. This will enable cross-origin prefetching using the Speculation Rules API.

[nuxt.config.ts]

export default defineNuxtConfig({
  experimental: {
    crossOriginPrefetch: true,
  },
})

Disable prefetch globally

It’s also possible to enable/disable prefetching all links globally for your app.

[nuxt.config.ts]

export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        prefetch: false,
      },
    },
  },
})

Props

RouterLink Props

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

to · string | RouteLocation

Any URL or a route location object from Vue Router.

custom · boolean

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’s custom prop.

exactActiveClass · string · default: "router-link-exact-active"

A class to apply on exact active links. Works the same as Vue Router’s exactActiveClass prop on internal links.

activeClass · string · default: "router-link-active"

A class to apply on active links. Works the same as Vue Router’s activeClass prop on internal links.

replace · boolean

Works the same as Vue Router’s replace prop on internal links.

ariaCurrentValue · string

An aria-current attribute value to apply on exact active links. Works the same as Vue Router’s ariaCurrentValue prop on internal links.

NuxtLink Props

href · string

An alias for to. If used with to, href will be ignored.

noRel · boolean

If set to true, no rel attribute will be added to the external link.

external · boolean

Forces the link to be rendered as an <a> tag instead of a Vue Router RouterLink.

prefetch · boolean

When enabled will prefetch middleware, layouts and payloads of links in the viewport.

prefetchOn · 'interaction' | 'visibility' | object

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 · boolean

Disables prefetching.

prefetchedClass · string

A class to apply to links that have been prefetched.

Anchor Props

target · string

A target attribute value to apply on the link.

rel · string · default: "noopener noreferrer"

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

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'
        prefetch: true,
        prefetchOn: { visibility: true },
      },
    },
  },
})

Custom Link Component

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

[app/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.

defineNuxtLink Signature

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 · string · default: "NuxtLink"

A name for the component.

externalRelAttribute · string · default: "noopener noreferrer"

A default rel attribute value applied on external links. Set it to "" to disable.

activeClass · string · default: "router-link-active"

A default class to apply on active links. Works the same as Vue Router’s linkActiveClass option.

exactActiveClass · string · default: "router-link-exact-active"

A default class to apply on exact active links. Works the same as Vue Router’s linkExactActiveClass option.

trailingSlash · 'append' | 'remove'

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 · boolean

Whether or not to prefetch links by default.

prefetchOn · object

Granular control of which prefetch strategies to apply by default.

prefetchedClass · string

A default class to apply to links that have been prefetched.