Fix: NuxtLink Props Cannot Be Used Together in Nuxt

What Causes This Warning?

This warning appears when you provide both to and href props to a <NuxtLink> component. These props serve similar purposes, so Nuxt ignores href and uses to.

The Problem

<template>
  <!-- ❌ Wrong - conflicting props -->
  <NuxtLink to="/about" href="/about-us">About</NuxtLink>

  <!-- ❌ Wrong - mixing internal and external -->
  <NuxtLink to="/products" href="https://external.com">Products</NuxtLink>
</template>

The Fix

Use Only to for Internal Links

<template>
  <!-- ✅ Correct - use to for internal routing -->
  <NuxtLink to="/about">About</NuxtLink>

  <!-- ✅ With route object -->
  <NuxtLink :to="{ path: '/products', query: { sort: 'price' } }">
    Products
  </NuxtLink>
</template>

Use Only href for External Links

<template>
  <!-- ✅ Correct - use href for external links -->
  <NuxtLink href="https://external.com">External Site</NuxtLink>

  <!-- ✅ Or use external prop with to -->
  <NuxtLink to="https://external.com" external>External Site</NuxtLink>
</template>

When to Use Each Prop

Prop	Use Case
to	Internal navigation (Vue Router)
href	External links, anchor links
external	Force external behavior with to

Common Patterns

Internal Navigation

<template>
  <!-- Simple path -->
  <NuxtLink to="/about">About Us</NuxtLink>

  <!-- Named route -->
  <NuxtLink :to="{ name: 'products-id', params: { id: 123 } }">
    Product 123
  </NuxtLink>

  <!-- With query parameters -->
  <NuxtLink :to="{ path: '/search', query: { q: 'shoes' } }">
    Search Shoes
  </NuxtLink>

  <!-- With hash -->
  <NuxtLink to="/docs#installation">Installation Guide</NuxtLink>
</template>

External Links

<template>
  <!-- External URL with href -->
  <NuxtLink href="https://github.com/nuxt">GitHub</NuxtLink>

  <!-- Opens in new tab -->
  <NuxtLink href="https://docs.nuxt.com" target="_blank">Docs</NuxtLink>

  <!-- External with noopener for security -->
  <NuxtLink
    href="https://external.com"
    target="_blank"
    rel="noopener noreferrer"
  >
    External Link
  </NuxtLink>
</template>

Dynamic Link Type

<script setup>
const props = defineProps<{
  link: string
}>()

const isExternal = computed(() =>
  props.link.startsWith('http') || props.link.startsWith('//')
)
</script>

<template>
  <!-- ✅ Conditional rendering based on link type -->
  <NuxtLink
    v-if="isExternal"
    :href="link"
    target="_blank"
  >
    <slot />
  </NuxtLink>
  <NuxtLink
    v-else
    :to="link"
  >
    <slot />
  </NuxtLink>
</template>

Or Use external Prop

<script setup>
const props = defineProps<{
  link: string
}>()

const isExternal = computed(() =>
  props.link.startsWith('http') || props.link.startsWith('//')
)
</script>

<template>
  <!-- ✅ Single NuxtLink with external prop -->
  <NuxtLink
    :to="link"
    :external="isExternal"
    :target="isExternal ? '_blank' : undefined"
  >
    <slot />
  </NuxtLink>
</template>

Migrating from href to to

Before (with warning)

<template>
  <NuxtLink href="/products">Products</NuxtLink>
</template>

After (correct)

<template>
  <NuxtLink to="/products">Products</NuxtLink>
</template>

Other Conflicting Props

to with target="_blank"

<!-- ❌ Internal link with _blank doesn't use Vue Router -->
<NuxtLink to="/about" target="_blank">About</NuxtLink>

<!-- ✅ If you need new tab for internal link -->
<a :href="`/about`" target="_blank">About</a>

<!-- Or mark as external to skip client navigation -->
<NuxtLink to="/about" external target="_blank">About</NuxtLink>

NuxtLink vs Regular Anchor

<template>
  <!-- NuxtLink - client-side navigation, prefetching -->
  <NuxtLink to="/about">About (SPA navigation)</NuxtLink>

  <!-- Regular anchor - full page reload -->
  <a href="/about">About (full reload)</a>
</template>

When to Use Regular <a>

• Download links
• Mailto/tel links
• When you explicitly want full page reload
• Non-Nuxt routes in the same domain

<template>
  <!-- These should use regular anchors -->
  <a href="/files/document.pdf" download>Download PDF</a>
  <a href="mailto:hello@example.com">Email Us</a>
  <a href="tel:+1234567890">Call Us</a>
</template>

Prefetch Behavior

<template>
  <!-- Default: prefetches when visible -->
  <NuxtLink to="/about">About</NuxtLink>

  <!-- Disable prefetching -->
  <NuxtLink to="/about" :prefetch="false">About</NuxtLink>

  <!-- Prefetch on hover only -->
  <NuxtLink to="/about" prefetch-on="hover">About</NuxtLink>
</template>

Quick Checklist

• Use to for internal routes (Vue Router navigation)
• Use href for external URLs
• Don’t combine to and href
• Use external prop to force external behavior
• Consider regular <a> for downloads, mailto, tel
• Add rel="noopener" for external links with target="_blank"