---
title: "Release: Unhead v2"
description: "Unhead v2 adds React, Svelte, Solid.js, and Angular adapters and rewrites the core rendering path."
publishedAt: "2025-03-24"
updatedAt: "2026-07-20"
navigation:
  title: "v2"
---

Unhead v2 adds adapters for React, Svelte, Solid.js, and Angular alongside the existing Vue integration. It also rewrites the core rendering path.

## Highlights

- **Multi-framework Support**: Added support for [React](https://react.dev), [Svelte](https://svelte.dev), [Solid.js](https://www.solidjs.com), and [Angular](https://angular.dev)
- **Rendering**: A rewritten core and cached tag resolution
- **Capo.js Integration**: Automatic tag ordering based on Capo.js recommendations
- **Dependencies**: A smaller runtime dependency set
- **Documentation**: New framework-specific installation and reactivity guides

## State of head management

JavaScript frameworks need to manage document metadata outside the application's DOM mount point, on both the server and client:

```html
<!DOCTYPE html>
<html>
  <head>
    <!-- Managed during server rendering and client navigation. -->
  </head>
  <body class="page">
    <div id="your-javascript-framework"></div>
    <script src="/your-javascript-framework.js"></script>
  </body>
</html>
```

Frameworks commonly expose a component or provider that collects these tags during rendering:

```vue [ComponentFoo]
<HeadProvider>
  <title>My Page</title>
  <meta name="description" content="My page description" />
  <link rel="canonical" href="https://example.com/my-page" />
</HeadProvider>
```

Examples include `<Helmet>`{lang="html"}, `<Head>`{lang="html"}, `<svelte:head>`{lang="html"}, and granular components such as `<Title>`{lang="html"}, `<Meta>`{lang="html"}, and `<Link>`{lang="html"}.

### Ecosystem

Framework ecosystems supplied many of the early solutions. Vue had [Vue Meta](https://vue-meta.nuxtjs.org/) and [VueUse Head](https://github.com/vueuse/head), while React applications often used [React Helmet](https://github.com/nfl/react-helmet).

[React v19](https://react.dev/blog/2024/12/05/react-19) added native metadata elements. Angular Router also exposes a [`title` property on routes](https://angular.dev/api/router/Route#title).

## A quick recap on Unhead

Unhead started as [`@vueuse/head`](https://github.com/vueuse/head) and later moved to [UnJS](https://unjs.io/). The npm registry recorded [948,265 downloads of `unhead` in the week before this release](https://api.npmjs.org/downloads/point/2025-03-17:2025-03-23/unhead), an average of more than 135,000 per day.

:UnheadDownloads{class="my-10 lg:-mx-20 lg:w-[125%] rounded overflow-hidden"}

Its main APIs are `useHead()`{lang="ts"} for document tags and `useSeoMeta()`{lang="ts"} for typed SEO metadata.

## v2 Release

For the original scope and discussion, see the [v2 roadmap](https://github.com/unjs/unhead/issues/395).

### New Framework Support

Unhead v2 adds React, Svelte, Solid.js, and Angular adapters with framework-specific reactivity and lifecycle handling.

:FrameworkSelectorMinimal{ignore-redirect}

```ts
import { useHead } from '@unhead/dynamic-import'

useHead({
  title: '👋 @FRAMEWORK_NAME@'
})
```

- **Vue** (`@unhead/vue`): [Installation](/docs/vue/head/guides/get-started/installation) and [Reactivity Guide](/docs/vue/head/guides/core-concepts/reactivity-and-context)
- **React** (`@unhead/react`): [Installation](/docs/react/head/guides/get-started/installation) and [Reactivity Guide](/docs/react/head/guides/core-concepts/reactivity)
- **Svelte** (`@unhead/svelte`): [Installation](/docs/svelte/head/guides/get-started/installation) and [Reactivity Guide](/docs/svelte/head/guides/core-concepts/reactivity)
- **Solid.js** (`@unhead/solid-js`): [Installation](/docs/solid-js/head/guides/get-started/installation) and [Reactivity Guide](/docs/solid-js/head/guides/core-concepts/reactivity)
- **Angular** (`@unhead/angular`): [Installation](/docs/angular/head/guides/get-started/installation) and [Reactivity Guide](/docs/angular/head/guides/core-concepts/reactivity)

Each adapter exposes the same core tag APIs through its framework's context and lifecycle primitives.

### ⚡ Runtime Performance Improvements

This release rewrites much of the core to reduce rendering work and improve tree-shaking.

**Rewritten Core**: The [core rewrite](https://github.com/unjs/unhead/pull/488) reduces work in the rendering path.

**Cached tag resolution**: Tags are now [cached between DOM renders](https://github.com/unjs/unhead/pull/504), reducing the work performed while switching pages.

**Leaner Core**: Code changes and opt-in features reduce the client and server bundle surface. The original release benchmarks and comparison environment were not retained, so exact historical timing and size claims have been omitted here.

:UnheadTwoGraphs

### Capo.js Sorting

Unhead v2 applies Capo.js sorting to tags by default. This places resource hints, stylesheets, synchronous scripts, and metadata in Capo.js's recommended order.

:CapoExample

### 📦 Bundle Improvements

**Single dependency:** Unhead relies on [hookable](https://github.com/unjs/hookable) for pluggability.

**ESM and dropped workspace packages:** Only ESM is now published, and workspace packages are deprecated in favor of subpath exports.

## 🔄 Upgrading to v2

Unhead provides a `legacy` subpath build for staged migrations.

See the [Migrate to v2](/docs/migration-guide/v2) guide.

## Roadmap at Release

At release, the roadmap included validation, higher-level script integrations, and Open Graph image generation.

### Short Term: Improved Tag Validation

Some tag attributes depend on another attribute. For example, a `<link rel="preload">` needs an `as` value.

At the time of the v2 release, Unhead's types did not enforce every such combination.

The roadmap considered three ways to catch invalid tag combinations:

- Improve the type system for optionally required attributes
- Implement [ESLint](https://eslint.org) rules to catch anything the types haven't
- Use a runtime plugin in development to validate resolved tags

### Medium Term: Third-Party Scripts

The roadmap proposed service-specific wrappers around `useScript()`{lang="ts"}, such as `useGoogleAnalytics()`{lang="ts"} and `useFacebookPixel()`{lang="ts"}.

These wrappers would connect script loading to framework lifecycles and expose typed service APIs.

```ts
const { proxy } = useGoogleAnalytics({
  id: 'UA-123456789',
})

proxy.gtag('page_view', {
  page_path: '/my-page',
})
```

### Exploratory: OG Image

The roadmap also explored turning HTML templates into Open Graph images from a composable.

```ts
useOgImage('<div class="bg-red-500">my image :)</div>')
```

## 🙏 Thank You

Thank you to everyone who contributed code, tests, and documentation.