Upgrade Guide

Migrate to v3 (from v2)

This section applies only if your Nuxt app or module directly installs Unhead v3. Nuxt manages its own Unhead dependency, so do not force-upgrade Nuxt's transitive copy.

Legacy Property Names

🚦 Impact Level: High

Current Unhead entry points omit DeprecationsPlugin. Rename these properties in code that directly uses Unhead v3. Nuxt may retain compatibility while upgrading its bundled version.

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

If you're using @unhead/schema-org directly (not through nuxt-schema-org), the plugin exports have changed:

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

Server Composable Aliases Deprecated

🚦 Impact Level: Low

The useServerHead, useServerHeadSafe, and useServerSeoMeta names are deprecated compatibility aliases in the Vue adapter. Use the standard composables instead.

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

If you need server-only head management:

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

Hooks

🚦 Impact Level: Low

If you're using Unhead hooks directly, the init hook was removed. dom:renderTag is deprecated and no longer called internally. dom:rendered is deprecated but still emitted; prefer the onRendered option on useHead(). Both dom:beforeRender and renderDOMHead() are now synchronous.

Migrate to v2 (from v1)

Nuxt 3.16 upgraded its built-in head manager to Unhead v2. Nuxt 3 uses a compatibility build, so most applications can upgrade without changing head calls.

Nuxt v4 Migration

Follow the official Nuxt v4 migration guide.

Key Changes

Nuxt handles these v2 integration changes:

• Client/server subpath exports: Nuxt configures these automatically
• Implicit context: Nuxt manages Vue context integration
• Template params and plugins: Nuxt includes the necessary plugins

For the full list of changes, check out the Vue Upgrade Guide.