The NuxtLink component may seem simple at first glance, but there’s a lot going on beneath the surface.

It’s one of the easiest Nuxt 3 components to use, while giving our apps a big performance boost.

Let’s see how it works, and how we can use it.

Instant Page Loads and Hybrid Rendering

Nuxt 3 uses Hybrid Rendering by default, which is a combination of server-side rendering (SSR) and Single-Page App (SPA) modes.

On the initial request, Nuxt uses SSR to quickly render the page and get it back to you. But after that, any page transitions are handled entirely in the browser in SPA mode — making it very fast.

To make this work, we replace all of our regular links with NuxtLink.

This component handles all of this for us — and plenty more.

How to use NuxtLink

The NuxtLink component is a drop-in replacement for any anchor tags:

<!-- Using an anchor tag -->
<a href="/articles">Articles</a>

<!-- Replace with NuxtLink -->
<NuxtLink to="/articles">Articles</NuxtLink>

Okay, not quite a straight drop-in, but pretty close.

It also works with external links, automatically adding in noopener and noreferrer attributes for security:

<!-- Using an anchor tag -->
<a href="www.masteringnuxt.com" rel="noopener noreferrer">Mastering Nuxt 3</a>

<!-- Replace with NuxtLink -->
<NuxtLink to="www.masteringnuxt.com">Mastering Nuxt 3</NuxtLink>

In some cases NuxtLink may not detect that the link is an external one, so you can tell it explicitly using the external prop:

<NuxtLink
  to="www.masteringnuxt.com"
  external
>
  Mastering Nuxt 3
</NuxtLink>

This component uses the RouterLink component from Vue Router internally, so there are lots of other props you can use to customize behaviour.

Opening Links in a New Tab

If you want your link to open in a new tab (or window, depending on how the user’s browser works), you can use the target attribute:

<NuxtLink
  to="/articles"
  target="_blank"
>
  Mastering Nuxt 3
</NuxtLink>

Prefetching Routes

With internal links, NuxtLink can check to see if it’s in the viewport in order so it can preload data before you even need it:

<NuxtLink to="/articles" prefetch>Articles</NuxtLink>

This behaviour is on by default, so you don’t even need to worry about it most of the time. But the prop is helpful if you need to disable it for some reason:

<NuxtLink to="/articles" :prefetch="false">Articles</NuxtLink>

We can also do the same thing with noPrefetch:

<NuxtLink to="/articles" no-prefetch>Articles</NuxtLink>

If the route has been prefetched, Nuxt will set a prefetchedClass on the link:

<NuxtLink
  to="/articles"
  prefetched-class="prefetched"
>
  Articles
</NuxtLink>

This can be very useful during debugging, but probably not as useful to your end users!

Customizing Your Own NuxtLink

You can also encapsulate a lot of these different configurations into your own link components if you want, using defineNuxtLink:

// ~/components/MyLink.ts

// Only colour prefetched links during development
export default defineNuxtLink({
  componentName: 'MyLink',
  prefetchedClass: process.env.NODE_ENV === 'development'
    ? 'prefetched'
    : undefined,
});

Here we create our own MyLink component that will set a special class on prefetched links, but only during development.

You can do a lot more with defineNuxtLink:

defineNuxtLink({
  componentName?: string;
  externalRelAttribute?: string;
  activeClass?: string;
  exactActiveClass?: string;
  prefetchedClass?: string;
  trailingSlash?: 'append' | 'remove'
}) => Component

If you want to learn more, I recommend going straight to the docs, or to the source code itself.