Upgrade Guide

Migrate to v3 (from v2)

Unhead v3 changes several core defaults and removes v2 compatibility behavior. This guide covers the changes relevant to Vue users.

Legacy Property Names

🚦 Impact Level: High

The current createHead() entry points omit DeprecationsPlugin. Rename these properties before upgrading; the deprecated plugin is still available for staged migrations.

children → innerHTML

useHead({
  script: [{
-   children: 'console.log("hello")',
+   innerHTML: 'console.log("hello")',
  }]
})

hid / vmid → key

useHead({
  meta: [{
-   hid: 'description',
+   key: 'description',
    name: 'description',
    content: 'My description'
  }]
})

body: true → tagPosition: 'bodyClose'

useHead({
  script: [{
    src: '/script.js',
-   body: true,
+   tagPosition: 'bodyClose',
  }]
})

Schema.org Plugin

🚦 Impact Level: High

The PluginSchemaOrg and SchemaOrgUnheadPlugin exports have been removed. Use UnheadSchemaOrg instead.

- import { PluginSchemaOrg } from '@unhead/schema-org/vue'
+ import { UnheadSchemaOrg } from '@unhead/schema-org/vue'

const head = createHead({
  plugins: [
-   PluginSchemaOrg()
+   UnheadSchemaOrg()
  ]
})

Server Composables Deprecated

🚦 Impact Level: Medium-High

The useServerHead, useServerHeadSafe, and useServerSeoMeta composables remain as deprecated aliases. Use the standard composables instead.

- import { useServerHead, useServerSeoMeta } from '@unhead/vue'
+ import { useHead, useSeoMeta } from '@unhead/vue'

- useServerHead({ title: 'My Page' })
+ useHead({ title: 'My Page' })

- useServerSeoMeta({ description: 'My description' })
+ useSeoMeta({ description: 'My description' })

If you need server-only head management, use conditional logic. Vite defines import.meta.env.SSR:

if (import.meta.env.SSR) {
  useHead({ title: 'Server Only' })
}

Vue Legacy Exports Deprecated

🚦 Impact Level: Medium

The /legacy export path remains available for migration compatibility and is scheduled for removal in v4. Move to the client or server entry point now:

- import { createHead } from '@unhead/vue/legacy'
+ import { createHead } from '@unhead/vue/client'
// or for SSR
+ import { createHead } from '@unhead/vue/server'

createHeadCore Removed

- import { createHeadCore } from '@unhead/vue'
+ import { createHead } from '@unhead/vue/server'
// or for client
+ import { createHead } from '@unhead/vue/client'

Core API Changes

🚦 Impact Level: Medium

headEntries() → entries Map

- const entries = head.headEntries()
+ const entries = [...head.entries.values()]

mode Option Removed

The mode option on head entries has been removed.

useHead({
  title: 'My Page',
- }, { mode: 'server' })
+ })

Hooks

🚦 Impact Level: Low

The init hook was removed. dom:renderTag remains in the type definitions for compatibility but is deprecated and no longer called internally. dom:rendered is also deprecated but is still emitted; prefer the onRendered entry option for entry-specific work.

The dom:beforeRender hook is now synchronous and renderDOMHead no longer returns a Promise:

- await renderDOMHead(head, { document })
+ renderDOMHead(head, { document })

The SSR hooks (ssr:beforeRender, ssr:render, ssr:rendered) are now synchronous and renderSSRHead no longer returns a Promise:

- const head = await renderSSRHead(head)
+ const head = renderSSRHead(head)

Other API Changes

• setHeadInjectionHandler was removed; head injection is handled automatically.
• resolveUnrefHeadInput and DeprecationsPlugin remain available as compatibility helpers. Avoid them in new code.

Type Changes

🚦 Impact Level: Low

- import type { Head, MetaFlatInput } from '@unhead/vue'
+ import type { HeadTag, MetaFlat } from '@unhead/vue'

Migrate to v2 (from v1)

Unhead v2 added adapters for other frameworks. This section covers the v1-to-v2 changes that affect Vue users.

Client / Server Subpath Exports

🚦 Impact Level: Critical

⚠️ Breaking Changes:

• createServerHead() and createHead() exports from unhead are removed

The path where you import createHead from has been updated to be a subpath export.

Client bundle:

-import { createHead } from '@unhead/vue'
+import { createHead } from '@unhead/vue/client'
import { createApp } from 'vue'

const app = createApp()
const head = createHead()
app.use(head)

Server bundle:

-import { createServerHead } from '@unhead/vue'
+import { createHead } from '@unhead/vue/server'
import { createApp } from 'vue'

const app = createApp()

-const head = createServerHead()
+const head = createHead()

app.use(head)

Create one client head in the browser, but a fresh server head for every request. A shared SSR application factory must not reuse a head from @unhead/vue/client; that constructor omits server defaults, Vue server resolvers, and payload support.

Remove Legacy Instance Annotations

V1 examples sometimes annotated the instance with VueHeadClient<MergeHead>. These types no longer describe the v2 factory. Remove the annotation and let createHead() infer its result:

-import type { MergeHead, VueHeadClient } from '@unhead/vue'
 import { createHead } from '@unhead/vue/client'

-const head = createHead() as unknown as VueHeadClient<MergeHead>
+const head = createHead()

Replace Legacy Alias Packages

Move direct imports from the compatibility packages to their v2 entry points:

Removed Implicit Context

🚦 Impact Level: Critical

⚠️ Breaking Changes:

• setHeadInjectionHandler() is removed
• Error may be thrown when using useHead() after async operations

The implicit context implementation kept a global instance of Unhead available so that you could use the useHead() composables anywhere in your application.

In v2, the core composables no longer have access to the Unhead instance. Instead, you must pass the Unhead instance to the composables if you'd like to use Unhead in a non-Vue context.

<script setup lang="ts">
// In Vue this happens in lifecycle hooks where we have async operations.
onMounted(async () => {
  await fetchSomeData()
  useHead({
    title: 'This will not work'
  })
})
</script>

If you're getting errors on your useHead() about context, check the Reactivity and Async Context guide.

Removed vmid, hid, children, body

🚦 Impact Level: High

Unhead v1 accepted the Vue Meta properties vmid, hid, children, and body.

You must update these properties to the appropriate replacement or remove them. See the v3 migration section for the replacements.

Opt-in Template Params & Tag Alias Sorting

🚦 Impact Level: High

Template parameters and tag alias sorting now require optional plugins:

import { AliasSortingPlugin, TemplateParamsPlugin } from '@unhead/vue/plugins'

createHead({
  plugins: [TemplateParamsPlugin, AliasSortingPlugin]
})

Vue 2 Support

🚦 Impact Level: Critical

Unhead v3 no longer supports Vue v2. If you're using Vue v2, you will need to lock your dependencies to the latest v1 version of Unhead.

Promise Input Support

🚦 Impact Level: Medium

Promise inputs are no longer resolved by core. Prefer awaiting them before passing the result to Unhead, or register the optional plugin when that is not possible:

import { createHead } from '@unhead/vue/client'
import { PromisesPlugin } from '@unhead/vue/plugins'

const unhead = createHead({
  plugins: [PromisesPlugin]
})

The plugin resolves values outside the synchronous tag pipeline. Pending entries are omitted from the current render, then rendered automatically on the client after resolving. Resolve inputs before SSR when they must appear in its first render.

Updated useScript()

🚦 Impact Level: High

⚠️ Breaking Changes:

• Script instance is no longer augmented as a proxy and promise
• script.proxy is rewritten for simpler, more stable behavior
• stub() and runtime hook script:instance-fn are removed

Replacing Promise Usage

const script = useScript()

-script.then(() => console.log('loaded')
+script.onLoaded(() => console.log('loaded'))

Replacing Proxy Usage

const script = useScript('..', {
  use() { return { foo: [] } }
})

-script.foo.push('bar')
+script.proxy.foo.push('bar')

Tag Sorting Updated

🚦 Impact Level: Low

Capo.js sorting is now the default. You can opt-out:

createHead({
  disableCapoSorting: true,
})

Default SSR Tags

🚦 Impact Level: Low

During SSR, Unhead now inserts these default tags:

• <meta charset="utf-8">
• <meta name="viewport" content="width=device-width, initial-scale=1">
• <html lang="en">

import { createHead } from '@unhead/vue/server'

// disable when creating the head instance
createHead({
  disableDefaults: true,
})

Or override the defaults:

import { useHead } from '@unhead/vue'

useHead({
  htmlAttrs: {
    lang: 'fr'
  }
})

CJS Exports Removed

🚦 Impact Level: Low

CommonJS exports have been removed in favor of ESM only.

-const { useHead } = require('@unhead/vue')
+import { useHead } from '@unhead/vue'

Deprecated @unhead/schema

🚦 Impact Level: Low

The @unhead/schema package is deprecated. Import from @unhead/vue/types instead.

-import { HeadTag } from '@unhead/schema'
+import { HeadTag } from '@unhead/vue/types'