---
title: "Installing Unhead with React"
description: "Set up Unhead in React with UnheadProvider and the useHead() hook. Includes a compatibility path for migrating from react-helmet."
canonical_url: "https://unhead.unjs.io/docs/react/head/guides/get-started/installation"
last_updated: "2026-07-21T05:10:37.980Z"
---
Install `@unhead/react`, wrap the application with `UnheadProvider`, and call `useHead()` in components. For SSR, inject the rendered tags with `transformHtmlTemplate()`.
Use the `` component for JSX-style declarations or `useHead()` for object input. If you are migrating from [`react-helmet`](https://github.com/nfl/react-helmet), Unhead also ships a compatibility component.
The examples follow [Vite's SSR structure](https://vite.dev/guide/ssr.html); the same client entry point works in a React SPA.
## Demos
- [StackBlitz - Unhead - Vite + React SSR](https://stackblitz.com/edit/github-5hqsxyid)
- [StackBlitz - Unhead - React SPA](https://stackblitz.com/edit/vitejs-vite-ggqxj5nx)
## Install Unhead
### 1. Add Dependency
Install the `@unhead/react` dependency in your project.
### 2. Set Up Client-Side Rendering
Create the browser instance from `@unhead/react/client`. In a Vite SSR app this usually belongs in `entry-client.ts`; in an SPA, put it in the main entry.
```tsx [src/entry-client.ts]
import { createHead, UnheadProvider } from '@unhead/react/client'
import { StrictMode } from 'react'
import { hydrateRoot } from 'react-dom/client'
import App from './App'
import './index.css'
const head = createHead()
hydrateRoot(
document.getElementById('root') as HTMLElement,
,
)
```
### 3. Set Up Server-Side Rendering
Serving your app as an SPA? You can [skip](#4-add-head-tags) this step.
For SSR, create a fresh instance from `@unhead/react/server` for each request and return it with the rendered app.
```tsx [src/entry-server.ts]
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 }
}
```
After React renders, pass the instance and complete HTML template to `transformHtmlTemplate()`:
```ts [server.ts]
import { transformHtmlTemplate } from '@unhead/react/server'
// ...
// Serve HTML
app.use('*all', async (req, res) => {
try {
// ...
const rendered = await render(url)
const html = transformHtmlTemplate(
rendered.head,
template.replace(``, rendered.html ?? '')
)
res.status(200).set({ 'Content-Type': 'text/html' }).send(html)
}
catch (e) {
// ...
}
})
// ..
```
### 4. Add Head Tags
The server head inserts three defaults:
- ``
- ``
- ``
Set server-only defaults through `init`. Keeping them in the server entry also keeps them out of the client bundle.
```ts [src/entry-server.ts]
import { createHead } from '@unhead/react/server'
export function render(_url: string) {
const head = createHead({
// change default initial lang
init: [
{
htmlAttrs: { lang: 'en' },
title: 'Default title',
titleTemplate: '%s - My Site',
},
]
})
const html = ``
return { html, head }
}
```
To add tags in your components, use either the `` component or the `useHead()` hook.
- `useHead()` accepts the full typed head object and entry options.
- `` accepts native head elements as children.
```tsx [App.tsx]
import { Head, useHead } from '@unhead/react'
export default function App() {
// a. use the hook
useHead({
title: 'Example Site',
meta: [
{ name: 'description', content: 'An example page description.' }
]
})
// b. use the component
return (
Example Site
Hello World
)
}
```
### 5. Enable Auto-Imports (Optional)
[unplugin-auto-import](https://github.com/unplugin/unplugin-auto-import) can provide the composables without explicit imports:
```ts [vite.config.ts]
import { hookImports } from '@unhead/react'
import AutoImport from 'unplugin-auto-import/vite'
export default defineConfig({
plugins: [
AutoImport({
imports: [
hookImports,
],
}),
// ...
]
})
```
## Next Steps
Hooks and components:
- [`useHead()`](/docs/head/api/composables/use-head)
- [`useSeoMeta()`](/docs/head/api/composables/use-seo-meta)
For `react-helmet`, see the [migration guide](/docs/react/head/guides/get-started/migrate-from-react-helmet).
Optional integrations:
- Add [`useSchemaOrg()`](/docs/schema-org/api/composables/use-schema-org) for structured data
- Use [`useScript()`](/docs/head/api/composables/use-script) for loading triggers and script lifecycle hooks