Canonical Plugin · Unhead [Unhead Home](https://unhead.unjs.io/ "Home") - [Docs](https://unhead.unjs.io/docs/angular/head/guides/get-started/overview) - [Tools](https://unhead.unjs.io/tools) - [Learn](https://unhead.unjs.io/learn/guides/what-is-capo) [Releases](https://unhead.unjs.io/releases) Search…```k`` /` [Unhead on GitHub](https://github.com/unjs/unhead) [User Guides](https://unhead.unjs.io/docs/angular/head/guides/get-started/overview) [API](https://unhead.unjs.io/docs/angular/head/api/get-started/overview) Angular - [Switch to Angular](https://unhead.unjs.io/docs/angular/head/guides/plugins/canonical) - [Switch to TypeScript](https://unhead.unjs.io/docs/typescript/head/guides/plugins/canonical) - [Switch to Vue](https://unhead.unjs.io/docs/vue/head/guides/plugins/canonical) - [Switch to React](https://unhead.unjs.io/docs/react/head/guides/plugins/canonical) - [Switch to Svelte](https://unhead.unjs.io/docs/svelte/head/guides/plugins/canonical) - [Switch to Solid.js](https://unhead.unjs.io/docs/solid-js/head/guides/plugins/canonical) - [Switch to Nuxt](https://unhead.unjs.io/docs/nuxt/head/guides/plugins/canonical) v3 (beta) You're viewing **Unhead v3 beta** documentation. Head - [Discord Support](https://discord.com/invite/275MBUBvgP) - [Angular Playground](https://stackblitz.com/edit/stackblitz-starters-e4x42yaz) - Get Started - [Overview](https://unhead.unjs.io/docs/angular/head/guides/get-started/overview) - [Introduction to Unhead](https://unhead.unjs.io/docs/angular/head/guides/get-started/intro-to-unhead) - [Starter Recipes](https://unhead.unjs.io/docs/angular/head/guides/get-started/starter-recipes) - [Installation](https://unhead.unjs.io/docs/angular/head/guides/get-started/installation) - [Upgrade Guide](https://unhead.unjs.io/docs/angular/head/guides/get-started/migration) - Core Concepts - [Titles & Title Templates](https://unhead.unjs.io/docs/angular/head/guides/core-concepts/titles) - [Tag Sorting & Placement](https://unhead.unjs.io/docs/angular/head/guides/core-concepts/positions) - [Class & Style Attributes](https://unhead.unjs.io/docs/angular/head/guides/core-concepts/class-attr) - [Inline Style & Scripts](https://unhead.unjs.io/docs/angular/head/guides/core-concepts/inner-content) - [Tag Deduplication](https://unhead.unjs.io/docs/angular/head/guides/core-concepts/handling-duplicates) - [DOM Event Handling](https://unhead.unjs.io/docs/angular/head/guides/core-concepts/dom-event-handling) - [Script Loading](https://unhead.unjs.io/docs/angular/head/guides/core-concepts/loading-scripts) - [Reactivity](https://unhead.unjs.io/docs/angular/head/guides/core-concepts/reactivity) - [Head Component](https://unhead.unjs.io/docs/angular/head/guides/core-concepts/components) - Advanced - [Extending Unhead](https://unhead.unjs.io/docs/angular/head/guides/advanced/extending-unhead) - [Bundle Optimizations](https://unhead.unjs.io/docs/angular/head/guides/advanced/client-only-tags) - [Build Plugins](https://unhead.unjs.io/docs/angular/head/guides/advanced/vite-plugin) - Plugins - [Template Params](https://unhead.unjs.io/docs/angular/head/guides/plugins/template-params) - [Alias Sorting](https://unhead.unjs.io/docs/angular/head/guides/plugins/alias-sorting) - [Canonical Plugin](https://unhead.unjs.io/docs/angular/head/guides/plugins/canonical) - [Infer SEO Meta](https://unhead.unjs.io/docs/angular/head/guides/plugins/infer-seo-meta-tags) - [Validate](https://unhead.unjs.io/docs/angular/head/guides/plugins/validate) Plugins # Canonical Plugin [Copy for LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/1.guides/plugins/canonical.md) Last updated Apr 5, 2026 by [Harlan Wilton](https://github.com/harlan-zw) in [docs: documentation content audit and formatting improvements (#718)](https://github.com/unjs/unhead/pull/718). On this page - [Why Do I Need Absolute URLs in Meta Tags?](#why-do-i-need-absolute-urls-in-meta-tags) - [What Tags Does the Plugin Transform?](#what-tags-does-the-plugin-transform) - [How Do I Set Up the Canonical Plugin?](#how-do-i-set-up-the-canonical-plugin) - [What Are the Configuration Options?](#what-are-the-configuration-options) - [How Do I Integrate with a CDN?](#how-do-i-integrate-with-a-cdn) - [Related](#related) **Quick Answer:** The Canonical plugin automatically generates `` tags and converts relative URLs to absolute URLs in your meta tags. Enable it with `CanonicalPlugin({ canonicalHost: 'https://mysite.com' })` in your head configuration. ## [Why Do I Need Absolute URLs in Meta Tags?](#why-do-i-need-absolute-urls-in-meta-tags) The Canonical Plugin automatically converts relative URLs to absolute URLs in your meta tags, which is essential for: - [Google SEO](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls): Requires absolute URLs for canonical links - [Facebook](https://developers.facebook.com/docs/sharing/webmasters/getting-started): Ignores relative image paths in Open Graph tags - [Twitter](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup): Requires absolute URLs for Twitter Card images ## [What Tags Does the Plugin Transform?](#what-tags-does-the-plugin-transform) The plugin transforms these tags automatically: - `og:image` and `twitter:image` meta tags - `og:url` meta tag - `rel="canonical"` link tag Before ``` ``` After ``` ``` ## [How Do I Set Up the Canonical Plugin?](#how-do-i-set-up-the-canonical-plugin) Install the plugin in both your server & client entries: Input ``` import { CanonicalPlugin } from 'unhead/plugins' const head = createHead({ plugins: [ CanonicalPlugin({ canonicalHost: 'https://mysite.com' }) ] }) ``` ## [What Are the Configuration Options?](#what-are-the-configuration-options) Input ``` interface CanonicalPluginOptions { // Your site's domain (required) canonicalHost?: string // Optional: Custom function to transform URLs customResolver?: (path: string) => string } ``` ### [What Happens If I Don't Set canonicalHost?](#what-happens-if-i-dont-set-canonicalhost) - If no `canonicalHost` is provided: - Client-side: Uses `window.location.origin` - SSR: Leaves URLs as-is (relative) Always set `canonicalHost` explicitly for consistent behavior across environments. ### [How Do I Customize URL Resolution?](#how-do-i-customize-url-resolution) Use `customResolver` to implement custom URL transformation logic: Input ``` CanonicalPlugin({ canonicalHost: 'https://mysite.com', customResolver: path => new URL(\`/cdn${path}\`, 'https://example.com').toString() }) ``` Example transformation: Before ``` ``` After ``` ``` ## [How Do I Integrate with a CDN?](#how-do-i-integrate-with-a-cdn) Point image assets to your CDN domain: Input ``` CanonicalPlugin({ canonicalHost: 'https://mysite.com', customResolver: (path) => { // Send image paths to CDN, keep other URLs on main domain if (path.match(/\.(jpg|png|webp|gif|svg)$/i)) return \`https://cdn.mysite.com${path}\` return \`https://mysite.com${path}\` } }) ``` ## [Related](#related) - [Template Params](https://unhead.unjs.io/docs/head/guides/plugins/template-params) - Dynamic template parameters - [Infer SEO Meta](https://unhead.unjs.io/docs/head/guides/plugins/infer-seo-meta-tags) - Auto-generate SEO tags [Edit this page](https://github.com/unjs/unhead/edit/main/docs/head/1.guides/plugins/canonical.md) [Markdown For LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/1.guides/plugins/canonical.md) Did this page help you? [Alias Sorting Order head tags with before: and after: prefixes. More readable than numeric priorities for script loading and CSS dependencies.](https://unhead.unjs.io/docs/head/guides/plugins/alias-sorting) [Infer SEO Meta Auto-generate og:title, og:description, and twitter:card from existing title and description. Reduce duplicate meta tag definitions.](https://unhead.unjs.io/docs/head/guides/plugins/infer-seo-meta-tags) On this page - [Why Do I Need Absolute URLs in Meta Tags?](#why-do-i-need-absolute-urls-in-meta-tags) - [What Tags Does the Plugin Transform?](#what-tags-does-the-plugin-transform) - [How Do I Set Up the Canonical Plugin?](#how-do-i-set-up-the-canonical-plugin) - [What Are the Configuration Options?](#what-are-the-configuration-options) - [How Do I Integrate with a CDN?](#how-do-i-integrate-with-a-cdn) - [Related](#related) [GitHub](https://github.com/unjs/unhead) [ Discord](https://discord.com/invite/275MBUBvgP) [ /llms.txt](https://unhead.unjs.io/llms.txt) [Part of the UnJS ecosystem](https://unjs.io/) ### Articles - [Announcing Unhead v2](https://unhead.unjs.io/v2) ### Tools - [Meta Tag Generator](https://unhead.unjs.io/tools/meta-tag-generator) - [OG Image Generator](https://unhead.unjs.io/tools/og-image-generator) - [Schema.org Generator](https://unhead.unjs.io/tools/schema-generator) ### Head - [Overview](https://unhead.unjs.io/docs/angular/head/guides/get-started/overview) - [Introduction to Unhead](https://unhead.unjs.io/docs/angular/head/guides/get-started/intro-to-unhead) - [Starter Recipes](https://unhead.unjs.io/docs/angular/head/guides/get-started/starter-recipes) ### Schema.org - [Introduction](https://unhead.unjs.io/docs/angular/schema-org/guides/get-started/overview) Copyright © 2025-2026 Harlan Wilton - [MIT License](https://github.com/unjs/unhead/blob/main/license)