---
title: "Upgrade Guide · Unhead"
meta:
  "og:description": "Learn how to migrate between Unhead versions for Angular users."
  "og:title": "Upgrade Guide · Unhead"
  description: "Learn how to migrate between Unhead versions for Angular users."
---

**Get Started**

# **Upgrade Guide**

[Copy for LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/0.angular/head/guides/0.get-started/2.migration.md)

Last updated **Jan 4, 2026** by [Harlan Wilton](https://github.com/harlan-zw) in [fix!: sync `renderSSRHead()` (#629)](https://github.com/unjs/unhead/pull/629).

**On this page **

## [Migrate to v3 (from v2)](#migrate-to-v3-from-v2)

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

### [Legacy Property Names](#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](#schemaorg-plugin)

🚦 Impact Level: High

If you're using `@unhead/schema-org`, the plugin exports have changed:

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

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

### [Core API Changes](#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. Use platform detection instead:

```
import { isPlatformBrowser } from '@angular/common'

if (isPlatformBrowser(this.platformId)) {
  this.head.push({ title: 'Client Only' })
}
```

### [Hooks](#hooks)

🚦 Impact Level: Low

The following hooks have been removed:

- `init` - No longer needed
- `dom:renderTag` - DOM rendering is now synchronous
- `dom:rendered` - Use code after `renderDOMHead()` instead

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)
```

[Edit this page](https://github.com/unjs/unhead/edit/main/docs/0.angular/head/guides/0.get-started/2.migration.md)

[Markdown For LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/0.angular/head/guides/0.get-started/2.migration.md)

**Did this page help you? **

[**Installation** Set up Unhead in Angular with provideClientHead() and useHead(). Works with Angular signals for reactive head tags. SSR supported.](https://unhead.unjs.io/docs/angular/head/guides/get-started/installation) [**Reactivity** Use Angular signals with useHead() for reactive head tags. Pass getter functions and use patch() for updates.](https://unhead.unjs.io/docs/angular/head/guides/core-concepts/reactivity)