Migrating from React Helmet to Unhead · Unhead [Unhead Home](https://unhead.unjs.io/ "Home") - [Docs](https://unhead.unjs.io/docs/react/head/guides/get-started/overview) - [Tools](https://unhead.unjs.io/tools) - [Learn](https://unhead.unjs.io/learn/guides/what-is-capo) [Releases](https://unhead.unjs.io/releases) Search…```k`` /` [Unhead on GitHub](https://github.com/unjs/unhead) [User Guides](https://unhead.unjs.io/docs/react/head/guides/get-started/overview) [API](https://unhead.unjs.io/docs/react/head/api/get-started/overview) [Releases](https://unhead.unjs.io/docs/react/releases/v3) React - [Switch to React](https://unhead.unjs.io/docs/react/head/guides/get-started/installation) - [Switch to TypeScript](https://unhead.unjs.io/docs/typescript/head/guides/get-started/installation) - [Switch to Vue](https://unhead.unjs.io/docs/vue/head/guides/get-started/installation) - [Switch to Svelte](https://unhead.unjs.io/docs/svelte/head/guides/get-started/installation) - [Switch to Solid.js](https://unhead.unjs.io/docs/solid-js/head/guides/get-started/installation) - [Switch to Angular](https://unhead.unjs.io/docs/angular/head/guides/get-started/installation) - [Switch to Nuxt](https://unhead.unjs.io/docs/nuxt/head/guides/get-started/installation) v3 (stable) Head - [Discord Support](https://discord.com/invite/275MBUBvgP) - [React Playground](https://stackblitz.com/edit/github-5hqsxyid) - Get Started - [Overview](https://unhead.unjs.io/docs/react/head/guides/get-started/overview) - [Introduction to Unhead](https://unhead.unjs.io/docs/react/head/guides/get-started/intro-to-unhead) - [Starter Recipes](https://unhead.unjs.io/docs/react/head/guides/get-started/starter-recipes) - [Installation](https://unhead.unjs.io/docs/react/head/guides/get-started/installation) - [Upgrade Guide](https://unhead.unjs.io/docs/react/head/guides/get-started/migration) - [Migrate React Helmet](https://unhead.unjs.io/docs/react/head/guides/get-started/migrate-from-react-helmet) - Core Concepts - [Titles & Title Templates](https://unhead.unjs.io/docs/react/head/guides/core-concepts/titles) - [Tag Sorting & Placement](https://unhead.unjs.io/docs/react/head/guides/core-concepts/positions) - [Class & Style Attributes](https://unhead.unjs.io/docs/react/head/guides/core-concepts/class-attr) - [Inline Style & Scripts](https://unhead.unjs.io/docs/react/head/guides/core-concepts/inner-content) - [Tag Deduplication](https://unhead.unjs.io/docs/react/head/guides/core-concepts/handling-duplicates) - [DOM Event Handling](https://unhead.unjs.io/docs/react/head/guides/core-concepts/dom-event-handling) - [Script Loading](https://unhead.unjs.io/docs/react/head/guides/core-concepts/loading-scripts) - [ Component](https://unhead.unjs.io/docs/react/head/guides/core-concepts/components) - [Reactivity](https://unhead.unjs.io/docs/react/head/guides/core-concepts/reactivity) - [StreamingNew](https://unhead.unjs.io/docs/react/head/guides/core-concepts/streaming) - Build Plugins - [Overview](https://unhead.unjs.io/docs/react/head/guides/build-plugins/overview) - [Tree-Shaking](https://unhead.unjs.io/docs/react/head/guides/build-plugins/tree-shaking) - [useSeoMeta Transform](https://unhead.unjs.io/docs/react/head/guides/build-plugins/seo-meta-transform) - [Minify Transform](https://unhead.unjs.io/docs/react/head/guides/build-plugins/minify-transform) - [Devtools](https://unhead.unjs.io/docs/react/head/guides/build-plugins/devtools) - Plugins - [Template Params](https://unhead.unjs.io/docs/react/head/guides/plugins/template-params) - [Alias Sorting](https://unhead.unjs.io/docs/react/head/guides/plugins/alias-sorting) - [Canonical Plugin](https://unhead.unjs.io/docs/react/head/guides/plugins/canonical) - [Infer SEO Meta](https://unhead.unjs.io/docs/react/head/guides/plugins/infer-seo-meta-tags) - [Minify](https://unhead.unjs.io/docs/react/head/guides/plugins/minify) - [Validate](https://unhead.unjs.io/docs/react/head/guides/plugins/validate) Get Started # Migrating from React Helmet to Unhead [Copy for LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/0.react/head/guides/0.get-started/migrate-from-react-helmet.md) Last updated Apr 6, 2026 by [Harlan Wilton](https://github.com/harlan-zw) in [feat(react): add @unhead/react/helmet compat export (#719)](https://github.com/unjs/unhead/pull/719). On this page - [Why Migrate from React Helmet?](#why-migrate-from-react-helmet) - [What's the Difference Between React Helmet and Unhead?](#whats-the-difference-between-react-helmet-and-unhead) - [How Do I Migrate from React Helmet to Unhead?](#how-do-i-migrate-from-react-helmet-to-unhead) - [Need Help?](#need-help) **Quick Answer:** For the fastest migration, swap your import to `@unhead/react/helmet` — it provides a drop-in `` component with the same API. Or replace `` with `useHead()` or `` for the full Unhead experience. ## [Why Migrate from React Helmet?](#why-migrate-from-react-helmet) [React Helmet](https://github.com/nfl/react-helmet) was the go-to solution for managing `` tags in React applications for years. However, its last major release was in 2020 and the project is now in maintenance mode. **Bundle size:** React Helmet 26.6 kB (9.2 kB gzipped) → Unhead 10.7 kB (4.5 kB gzipped) — **60% smaller** [Unhead](https://unhead.unjs.io/) offers a modern alternative with: - Full TypeScript safety - DOM event handlers - Advanced DOM patching algorithm built for reactive frameworks - Automatic [Capo.js-based tag sorting](https://unhead.unjs.io/docs/head/guides/core-concepts/positions) for optimal page load performance - Ecosystem of extras: `useSchemaOrg()`, `useScript()`, and more ## [What's the Difference Between React Helmet and Unhead?](#whats-the-difference-between-react-helmet-and-unhead) React Helmet uses a `` component to manage head tags. Unhead provides a `` component, offering a similar API. React Helmet ``` import { Helmet } from 'react-helmet' function App() { return ( My Site ) } ``` Unhead ``` import { Head } from '@unhead/react' function App() { return ( My Site ) } ``` ## [How Do I Migrate from React Helmet to Unhead?](#how-do-i-migrate-from-react-helmet-to-unhead) ### [Quick Migration with `@unhead/react/helmet`](#quick-migration-with-unheadreacthelmet) For the fastest migration path, Unhead provides a drop-in `` component that supports the same API as react-helmet — including `defaultTitle`, `titleTemplate`, and `onChangeClientState`. #### [1. Swap Your Dependencies](#_1-swap-your-dependencies) ``` npm remove react-helmet npm install @unhead/react ``` #### [2. Update Your Imports](#_2-update-your-imports) ``` -import { Helmet } from 'react-helmet' +import { Helmet } from '@unhead/react/helmet' ``` That's it — your existing `` usage will work as-is. On the client, `` automatically creates and manages a head instance, so no provider is needed. The `defaultTitle`, `titleTemplate`, and `onChangeClientState` props are all supported. For SSR, you still need to wrap your app with `` so you can pass the head instance to `renderSSRHead()`. See [Update Server Rendering](#4-update-server-rendering) below. ``` import { Helmet } from '@unhead/react/helmet' function App() { return ( console.log(newState)} > Page Title ) } ``` The `encodeSpecialCharacters` and `defer` props are accepted for compatibility but have no effect — Unhead handles these automatically. ### [3. Full Migration to `` (Optional)](#_3-full-migration-to-head-optional) If you'd prefer to adopt the Unhead API directly, replace `` with ``: ``` -import { Helmet } from 'react-helmet' +import { Head } from '@unhead/react' function Title() { return (
- - Hello World - + + Hello World +

Hello World

) } ``` ### [4. Update Server Rendering](#_4-update-server-rendering) If you're using SSR, update your server code: src/entry-server.tsx ``` import { createHead, UnheadProvider } from '@unhead/react/server' import { StrictMode } from 'react' import { renderToString } from 'react-dom/server' import App from './App' export function render(_url: string) { const head = createHead() const html = renderToString( , ) return { html, head } } ``` ### [5. What's Next?](#_5-whats-next) You've successfully migrated from React Helmet to Unhead. Check out some of the Unhead concepts: - [Tag Placement](https://unhead.unjs.io/docs/head/guides/core-concepts/positions) - [DOM Event Handling](https://unhead.unjs.io/docs/head/guides/core-concepts/dom-event-handling) - [Handling Duplicates](https://unhead.unjs.io/docs/head/guides/core-concepts/handling-duplicates) ## [Need Help?](#need-help) If you run into issues during migration: - File an issue on [GitHub](https://github.com/unjs/unhead) - Join our [Discord community](https://discord.gg/unjs) [Edit this page](https://github.com/unjs/unhead/edit/main/docs/0.react/head/guides/0.get-started/migrate-from-react-helmet.md) [Markdown For LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/0.react/head/guides/0.get-started/migrate-from-react-helmet.md) Did this page help you? [Upgrade Guide Learn how to migrate between Unhead versions for React users.](https://unhead.unjs.io/docs/react/head/guides/get-started/migration) [ Component JSX-based head management with Head, Title, Meta, Link, Script components. HTML-like syntax alternative to useHead().](https://unhead.unjs.io/docs/react/head/guides/core-concepts/components) On this page - [Why Migrate from React Helmet?](#why-migrate-from-react-helmet) - [What's the Difference Between React Helmet and Unhead?](#whats-the-difference-between-react-helmet-and-unhead) - [How Do I Migrate from React Helmet to Unhead?](#how-do-i-migrate-from-react-helmet-to-unhead) - [Need Help?](#need-help) [GitHub](https://github.com/unjs/unhead) [ Discord](https://discord.com/invite/275MBUBvgP) [ /llms.txt](https://unhead.unjs.io/llms.txt) [Part of the UnJS ecosystem](https://unjs.io/) ### Head Management - [Getting Started](https://unhead.unjs.io/docs/react/head/guides/get-started/overview) - [useHead](https://unhead.unjs.io/docs/react/head/api/composables/use-head) - [useSeoMeta](https://unhead.unjs.io/docs/react/head/api/composables/use-seo-meta) - [useHeadSafe](https://unhead.unjs.io/docs/react/head/api/composables/use-head-safe) - [useScript](https://unhead.unjs.io/docs/react/head/api/composables/use-script) ### Schema.org - [Getting Started](https://unhead.unjs.io/docs/react/schema-org/guides/get-started/overview) - [useSchemaOrg](https://unhead.unjs.io/docs/react/schema-org/api/composables/use-schema-org) - [Nodes](https://unhead.unjs.io/docs/react/schema-org/guides/core-concepts/nodes) - [Recipes](https://unhead.unjs.io/docs/react/schema-org/guides/recipes/identity) ### Guides - [Titles](https://unhead.unjs.io/docs/react/head/guides/core-concepts/titles) - [Streaming SSR](https://unhead.unjs.io/docs/react/head/guides/core-concepts/streaming) - [DOM Events](https://unhead.unjs.io/docs/react/head/guides/core-concepts/dom-event-handling) - [Plugins](https://unhead.unjs.io/docs/react/head/guides/plugins/template-params) ### Tools - [Meta Tag Generator](https://unhead.unjs.io/tools/meta-tag-generator) - [OG Image Generator](https://unhead.unjs.io/tools/og-image-generator) - [Schema.org Generator](https://unhead.unjs.io/tools/schema-generator) - [Capo.js Analyzer](https://unhead.unjs.io/tools/capo-analyzer) ### Articles - [What is Capo.js?](https://unhead.unjs.io/learn/guides/what-is-capo) ### Research - [State of in 2026](https://unhead.unjs.io/learn/research/state-of-head-2026) - [Streaming Head Performance](https://unhead.unjs.io/learn/research/streaming-head-performance) - [Capo.js Performance Research](https://unhead.unjs.io/learn/research/capo-performance-research) Copyright © 2025-2026 Harlan Wilton - [MIT License](https://github.com/unjs/unhead/blob/main/license)