Unhead

Introduction

Unhead has first-class support for Vue. In fact much of the code belongs to the original @vueuse/head repo which was a Vue 3 version of Vue Meta.

Vue Unhead works both for CSR and SSR, and it's designed to be framework-agnostic, so you can use it with any Vue setup.

This guide assumes you're following a similar structure to the vite-ssr-vue template or a SPA Vue setup.

Using Nuxt? Unhead is already integrated, and you can skip this guide.

Demos

Setup

1. Add Dependency

Install @unhead/vue dependency to your project. The next tag is for v2 of Unhead.

bash
pnpm add @unhead/vue@next

Using Vue 2

In Unhead v2, official support for Vue 2 has been dropped. If you're using Vue 2, you will need to install v1 of @unhead/vue@^1 instead.

bash
pnpm add @unhead/vue@^1

To continue, please follow the v1 Unhead Vue installation.

2. Setup Client-Side Rendering

To begin with, we'll import the function to initialize Unhead in our client Vue app from @unhead/vue/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 Vue app entry instead.

src/entry-client.ts
import './style.css'
import { createApp } from './main'
import { createHead } from '@unhead/vue/client'

const { app } = createApp()
const head = createHead()
app.use(head)

app.mount('#app')

3. Setup Server-Side Rendering

Serving your app as an SPA? You can skip 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/vue/server instead and add the head in the return object.

src/entry-server.ts
import { createHead } from '@unhead/vue/server'
import { renderToString } from 'vue/server-renderer'
import { createApp } from './main'

export async function render(_url: string) {
  const { app } = createApp()
  const head = createHead()
  app.use(head)

  const ctx = {}
  const html = await renderToString(app, ctx)

  return { html, head }
}

Now we need to render out the head tags after Vue 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/vue/server'
// ...

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

    const rendered = await render(url)

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

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

4. Your First 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/vue/server'

export async function render(_url: string) {
  // ...
  const head = createHead({
    init: [
      // change default initial lang
      {
        title: 'Default title',
        titleTemplate: '%s | My Site',
        htmlAttrs: { lang: 'fr' }
      },
    ]
  })
  // ...
}

Feel free to play around with adding tags to your apps. Here's an example of adding some styles to the body.

src/App.vue
<script setup lang="ts">
import { useHead } from '@unhead/vue'

useHead({
  bodyAttrs: {
    style: 'background: salmon; color: cyan;'
  },
})
</script>

5. Optional: Auto-Imports

If you're using unplugin-auto-import, you can automatically import the composables.

vite.config.ts
import { unheadVueComposablesImports } from '@unhead/vue'
import AutoImport from 'unplugin-auto-import/vite'

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

Next Steps

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

You can get started with any of the composables:

Or explore some of the optional extras:

Did this page help you?

Wrapping Composables

Get started with Unhead by installing the dependency to your project.

Vue Reactivity

Master Vue and Unhead by following the best practices.