Installing Unhead with Svelte · Unhead

[Unhead Home](https://unhead.unjs.io/ "Home")

- [Docs](https://unhead.unjs.io/docs/svelte/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/svelte/head/guides/get-started/overview)

[API](https://unhead.unjs.io/docs/svelte/head/api/get-started/overview)

[Releases](https://unhead.unjs.io/docs/svelte/releases/v3)

Svelte

- [Switch to Svelte](https://unhead.unjs.io/docs/svelte/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 React](https://unhead.unjs.io/docs/react/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)
- [Svelte Playground](https://stackblitz.com/edit/github-ckbygkxk)

- Get Started
  - [Overview](https://unhead.unjs.io/docs/svelte/head/guides/get-started/overview)
  - [Introduction to Unhead](https://unhead.unjs.io/docs/svelte/head/guides/get-started/intro-to-unhead)
  - [Starter Recipes](https://unhead.unjs.io/docs/svelte/head/guides/get-started/starter-recipes)
  - [Installation](https://unhead.unjs.io/docs/svelte/head/guides/get-started/installation)
  - [Upgrade Guide](https://unhead.unjs.io/docs/svelte/head/guides/get-started/migration)
  - [SvelteKit](https://unhead.unjs.io/docs/svelte/head/guides/get-started/sveltekit)
- Core Concepts
  - [Titles & Title Templates](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/titles)
  - [Tag Sorting & Placement](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/positions)
  - [Class & Style Attributes](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/class-attr)
  - [Inline Style & Scripts](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/inner-content)
  - [Tag Deduplication](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/handling-duplicates)
  - [DOM Event Handling](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/dom-event-handling)
  - [Script Loading](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/loading-scripts)
  - [Reactivity](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/reactivity)
  - [StreamingNew](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/streaming)
- Build Plugins
  - [Overview](https://unhead.unjs.io/docs/svelte/head/guides/build-plugins/overview)
  - [Tree-Shaking](https://unhead.unjs.io/docs/svelte/head/guides/build-plugins/tree-shaking)
  - [useSeoMeta Transform](https://unhead.unjs.io/docs/svelte/head/guides/build-plugins/seo-meta-transform)
  - [Minify Transform](https://unhead.unjs.io/docs/svelte/head/guides/build-plugins/minify-transform)
  - [Devtools](https://unhead.unjs.io/docs/svelte/head/guides/build-plugins/devtools)
- Plugins
  - [Template Params](https://unhead.unjs.io/docs/svelte/head/guides/plugins/template-params)
  - [Alias Sorting](https://unhead.unjs.io/docs/svelte/head/guides/plugins/alias-sorting)
  - [Canonical Plugin](https://unhead.unjs.io/docs/svelte/head/guides/plugins/canonical)
  - [Infer SEO Meta](https://unhead.unjs.io/docs/svelte/head/guides/plugins/infer-seo-meta-tags)
  - [Minify](https://unhead.unjs.io/docs/svelte/head/guides/plugins/minify)
  - [Validate](https://unhead.unjs.io/docs/svelte/head/guides/plugins/validate)

Get Started

# Installing Unhead with Svelte

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

Last updated Apr 5, 2026 by [Harlan Wilton](https://github.com/harlan-zw) in [docs: documentation content audit and formatting improvements (#718)](https://github.com/unjs/unhead/pull/718).

On this page

- [Introduction](#introduction)
- [Setup](#setup)
- [Next Steps](#next-steps)

## [Introduction](#introduction)

Unhead has first-class support for Svelte, improving the developer experience and performance of using head tags in your app.

**Quick Start:** Install `@unhead/svelte`, create head with `createHead()`, and use `setContext()` to provide it. Use `useHead()` in components with `$effect()` for reactivity.

It provides advanced features in comparison to Svelte's in built `<svelte:head>` component, supporting a more diverse set of use cases from SEO, structured data and script loading.

It's designed to work with any Svelte setup, however this guide assumes you're following a similar structure to the [Vite: ssr-svelte-ts](https://github.com/bluwy/create-vite-extra/tree/master/template-ssr-Svelte-ts) template or a Vite SPA.

Using [SvelteKit](https://kit.svelte.dev/)? See the dedicated [SvelteKit integration guide](https://unhead.unjs.io/docs/svelte/head/guides/get-started/sveltekit) instead.

### [Demos](#demos)

- [StackBlitz - Unhead + Vite + Svelte SSR](https://stackblitz.com/edit/github-ckbygkxk)
- [StackBlitz - Unhead + Vite + Svelte SPA](https://stackblitz.com/edit/vitejs-vite-tfv9egtq)

## [Setup](#setup)

### [1. How do I install Unhead for Svelte?](#_1-how-do-i-install-unhead-for-svelte)

Install `@unhead/svelte` dependency to your project.

pnpm

bun

npm

yarn

bash

`pnpm add @unhead/svelte@next`

### [2. How do I set up client-side rendering?](#_2-how-do-i-set-up-client-side-rendering)

To begin with, we'll import the function to initialize Unhead in our _client_ Svelte app from `@unhead/svelte/client`.

In Vite this entry file is typically named `entry-client.ts`. If you're not server-side rendering, you can add this to your main Svelte app entry instead.

src/entry-client.ts

```
import { createHead, UnheadContextKey } from '@unhead/svelte/client'
import { hydrate } from 'svelte'
import App from './App.svelte'
import './app.css'

// SSR or SPA usage

const unhead = createHead()
const context = new Map()
context.set(UnheadContextKey, unhead)

hydrate(App, {
  target: document.getElementById('app')!,
  context
})
```

src/main.ts

```
import { createHead, UnheadContextKey } from '@unhead/svelte/client'
import { mount } from 'svelte'
import App from './App.svelte'
import './app.css'

// SPA usage

const unhead = createHead()
const context = new Map()
context.set(UnheadContextKey, unhead)

const app = mount(App, {
  target: document.getElementById('app')!,
  context,
})

export default app
```

### [3. How do I set up server-side rendering?](#_3-how-do-i-set-up-server-side-rendering)

Serving your app as an SPA? You can [skip](#4-how-do-i-add-head-tags) this step.

Setting up server-side rendering is more complicated as it requires rendering out the tags to the HTML string before sending it to the client.

We'll start with setting up the plugin in the _server_ entry this time. Make sure to import from `@unhead/svelte/server` instead and add the `head` in the return object.

src/entry-server.ts

```
import { createHead, UnheadContextKey } from '@unhead/svelte/server'
import { render as _render } from 'svelte/server'
import App from './App.svelte'

export function render(_url: string) {
  const unhead = createHead()
  const context = new Map()
  context.set(UnheadContextKey, unhead)
  return {
    render: _render(App, {
      context,
    }),
    unhead,
  }
}
```

Now we need to render out the head tags _after_ Svelte has rendered the app.

Within your `server.js` file or wherever you're handling the template logic, you need to transform the template data for the head tags using `transformHtmlTemplate()`.

server.ts

```
import { transformHtmlTemplate } from '@unhead/svelte/server'
// ...

// Serve HTML
app.use('*all', async (req, res) => {
  try {
    // ...

    const rendered = await render(url)
    const html = await transformHtmlTemplate(
      rendered.unhead,
      template
        .replace(\`<!--app-head-->\`, rendered.head ?? '')
        .replace(\`<!--app-html-->\`, rendered.html ?? '')
    )

    res.status(200).set({ 'Content-Type': 'text/html' }).send(html)
  }
  catch (e) {
    // ...
  }
})
// ..
```

### [4. How do I add head tags?](#_4-how-do-i-add-head-tags)

Done! Your app should now be rendering head tags on the server and client.

To improve your apps stability, Unhead will now insert important default tags for you.

- `<meta charset="utf-8">`
- `<meta name="viewport" content="width=device-width, initial-scale=1">`
- `<html lang="en">`

You may need to change these for your app requirements, for example you may want to change the default language. Adding tags in your server entry means you won't add any weight to your client bundle.

src/entry-server.ts

```
import { createHead } from '@unhead/svelte/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 = \`<!-- your html -->\`
  return { html, head }
}
```

For adding tags in your components, you can use the `useHead()` or `useSeoMeta()` composables.

App.svelte

```
<script lang="ts">
  import { useHead } from '@unhead/svelte'

  // a.
  useHead({
    title: 'My Awesome Site',
    meta: [
      { name: 'description', content: 'My awesome site description' }
    ]
  })

  // b.
  useSeoMeta({
    title: 'My Awesome Site',
    description: 'My awesome site description'
  })
</script>
```

For handling reactive input, check out the [Reactivity](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/reactivity) guide.

### [5. How do I enable auto-imports? (Optional)](#_5-how-do-i-enable-auto-imports-optional)

If you're using [unplugin-auto-import](https://github.com/antfu/unplugin-auto-import), you can automatically import the composables.

vite.config.ts

```
import { autoImports } from '@unhead/svelte'
import AutoImport from 'unplugin-auto-import/vite'

export default defineConfig({
  plugins: [
    AutoImport({
      imports: [
        autoImports,
      ],
    }),
    // ...
  ]
})
```

## [Next Steps](#next-steps)

Your Svelte app is now setup for head management, congrats! 🎉

You can get started with [reactive input](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/reactivity) for any of the hooks or components:

- [`useHead()`](https://unhead.unjs.io/docs/head/api/composables/use-head)
- [`useSeoMeta()`](https://unhead.unjs.io/docs/head/api/composables/use-seo-meta)

Or explore some of the optional extras:

- Add [`useSchemaOrg()`](https://unhead.unjs.io/docs/schema-org/api/composables/use-schema-org) for structured data
- Use [`useScript()`](https://unhead.unjs.io/docs/head/api/composables/use-script) for performance optimized script loading

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

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

Did this page help you?

[Installation Add Schema.org to Solid.js apps with @unhead/schema-org. Setup defineWebSite(), defineWebPage() for Google Rich Results.](https://unhead.unjs.io/docs/solid-js/schema-org/guides/get-started/installation) [Upgrade Guide Learn how to migrate between Unhead versions for Svelte users.](https://unhead.unjs.io/docs/svelte/head/guides/get-started/migration)

On this page

- [Introduction](#introduction)
- [Setup](#setup)
- [Next Steps](#next-steps)

[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/svelte/head/guides/get-started/overview)
- [useHead](https://unhead.unjs.io/docs/svelte/head/api/composables/use-head)
- [useSeoMeta](https://unhead.unjs.io/docs/svelte/head/api/composables/use-seo-meta)
- [useHeadSafe](https://unhead.unjs.io/docs/svelte/head/api/composables/use-head-safe)
- [useScript](https://unhead.unjs.io/docs/svelte/head/api/composables/use-script)

### Schema.org

- [Getting Started](https://unhead.unjs.io/docs/svelte/schema-org/guides/get-started/overview)
- [useSchemaOrg](https://unhead.unjs.io/docs/svelte/schema-org/api/composables/use-schema-org)
- [Nodes](https://unhead.unjs.io/docs/svelte/schema-org/guides/core-concepts/nodes)
- [Recipes](https://unhead.unjs.io/docs/svelte/schema-org/guides/recipes/identity)

### Guides

- [Titles](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/titles)
- [Streaming SSR](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/streaming)
- [DOM Events](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/dom-event-handling)
- [Plugins](https://unhead.unjs.io/docs/svelte/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 <head> 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)