Configure Canonical URLs

Introduction

A canonical URL tells search engines which version of a page is the "main" one. Nuxt SEO automatically sets this for you using your site URL and current route path.

Multiple URLs often point to the same content (www vs non-www, trailing slashes). The canonical URL prevents duplicate content issues and confusion for end-users.

Learn more about canonical URLs with the Canonical Link Tag guide.

Canonical Head Tag

Nuxt SEO automatically sets a canonical URL meta tag for you. This tag is generated from the site URL and the current route path.

<head>
    <!-- ... -->
    <link rel="canonical" href="https://example.com/my-page" />
</head>

Overriding the Canonical URL

The auto-generated tag is registered at low priority, so a page-level useHead call with the same rel="canonical" link replaces it (canonical links dedupe by rel, not by URL):

useHead({
  link: [
    { rel: 'canonical', href: 'https://example.com/preferred-url' },
  ],
})

This is the common case for paginated or filtered pages that should all canonicalize to a single parent URL.

There's no dedicated option to disable canonical generation for a single page: setting href explicitly (as above) is the supported way to change it. Setting automaticDefaults: false module-wide turns off canonical generation along with every other automatic default (title template, Open Graph tags, og:locale), which is rarely what you want for just the canonical tag.

canonicalLowercase

By default, the canonical URL is generated in lowercase. This is to ensure that the canonical URL is consistent and avoids any issues with case sensitivity.

The same rule applies to every URL the module emits for the page: og:url, useShareLinks() links, and the Schema.org BreadcrumbList item URLs. The to links from useBreadcrumbItems() keep their case, so navigation still matches your routes.

While it's recommended to keep this on, if you need to disable this feature, you can do so by setting canonicalLowercase to false.

export default defineNuxtConfig({
  seo: {
    canonicalLowercase: false
  }
})

canonicalQueryWhitelist

The canonical URL is generated from:

• site.url. Your Site Config url.
• $route.path: The current route path.
• canonicalQueryWhitelist: A list of query parameters that should be included in the canonical URL.

By default, the canonicalQueryWhitelist includes a number of common query parameters that will modify the page content:

• page
• sort
• filter
• search
• q
• category
• tag

You can override this by providing your own list of query parameters that should be included in the canonical URL.

export default defineNuxtConfig({
  seo: {
    canonicalQueryWhitelist: ['myCustomQuery']
  }
})

Redirect To Canonical

In some cases it may be preferred to redirect all non-canonical URLs to the canonical URL.

This redirect is optional and disabled by default.

export default defineNuxtConfig({
  seo: {
    redirectToCanonicalSiteUrl: true
  }
})

Verifying

Check the rendered <head> for the tag, either with your browser's view-source or:

curl -s https://example.com/my-page | grep 'rel="canonical"'

Record the edit date and compare Google's last crawl with your deployed canonical. Google Search timelines explains why a correct live tag does not prove Google has adopted the change.

In production, cross-check against the URL Inspection report in Google Search Console, under "Google-selected canonical" — if it disagrees with your declared canonical, Google is treating another URL as more authoritative (usually a signal of thin or duplicate content, not a tag misconfiguration).