Upgrade Guide

Migrate to v3 (from v2)

Unhead v3 removes all deprecated APIs and focuses on performance improvements.

Legacy Property Names

🚦 Impact Level: High

The DeprecationsPlugin that automatically converted legacy property names has been removed. You must update your head entries to use the current property names.

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 Composables Removed

🚦 Impact Level: Low

The useServerHead, useServerHeadSafe, and useServerSeoMeta composables have been removed.

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

• init hook removed
• dom:renderTag hook removed
• dom:rendered hook removed
• dom:beforeRender is now synchronous
• renderDOMHead is now synchronous

Migrate to v2 (from v1)

As of Nuxt 3.16, Unhead v2 is the default version.

Nuxt v4 Migration

The best resource for managing the migration is the official Nuxt v4 migration guide.

Key Changes

Most v2 changes are handled automatically by Nuxt:

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

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