Nuxt/docs/3.api/1.components/4.nuxt-link.md

title	description	links
<NuxtLink>	Nuxt provides <NuxtLink> component to handle any kind of links within your application.	label icon to size Source i-simple-icons-github https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-link.ts xs

::callout <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>

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

In this example, we use <NuxtLink> with target, 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 Router
• custom: 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: A class to apply on exact active links. Works the same as Vue Router's exact-active-class prop on internal links. Defaults to Vue Router's default "router-link-exact-active")
• replace: Works the same as Vue Router's replace prop on internal links
• ariaCurrentValue: An aria-current attribute value to apply on exact active links. Works the same as Vue Router's aria-current-value prop on internal links
• activeClass: A class to apply on active links. Works the same as Vue Router's active-class prop on internal links. Defaults to Vue Router's default ("router-link-active")

NuxtLink

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

::callout 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

::callout{color="amber" icon="i-ph-warning-duotone"} These options will likely be moved elsewhere in the future, such as into 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 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")
• prefetchedClass: A default class to apply to links that have been prefetched.
• 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.

:link-example{to="/docs/examples/routing/pages"}