Experimental features for Nuxt SEO / head management.

△ nuxt-unhead

NPM versionNPM DownloadsGitHub stars

Experimental features for Nuxt v3 head management. Powered by Unhead.

Status: Stable
Please report any issues 🐛
Made possible by my Sponsor Program 💖
Follow me @harlan_zw 🐦 • Join Discord for help

ℹ️ Looking for a complete SEO solution? Check out Nuxt SEO Kit.


Unlock all Unhead features and more:

  • 🖥️ 0kb runtime tags useServerHead
  • ✨ Automatic social share meta tags
  • 🤖 Debug head tags component DebugHead
  • 🌳 Fully typed Head Schema with href and src file auto-completion
  • 🧩 Title template tokens: Use public runtime config in your templates: %s %titleSeperator %siteName.
  • 🪝 Runtime hooks: head:tags, head:entries
  • 📦 Load your asset files directly using aliases href: '~/assets/style.css' (Experimental)


This module was built to test bug fixes as well as experimental new features which may land into the Nuxt core.


npm install --save-dev nuxt-unhead# Using yarnyarn add --dev nuxt-unhead



export default defineNuxtConfig({  modules: [    'nuxt-unhead',  ],})

Module Configuration

Config key: unhead


export default defineNuxtConfig({  modules: ['nuxt-unhead'],  unhead: {    // config (see below)  },  //...})


Runtime Config Template Tokens

When defining your titleTemplate, title or meta content as strings, you can use tokens to reference values from your resolved runtime config.

For example, the default title template introduced by this module is %s %titleSeparator %siteName.

This uses the following:

  • %s - The title of the page.
  • %titleSeparator - runtimeConfig.public.titleSeparator
  • %siteName - runtimeConfig.public.siteName

To provide the values for these tokens, you can update them in your nuxt config.


export default defineNuxtConfig({  runtimeConfig: {    public: {      siteName: 'My cool site',      titleSeparator: '|',    }  },})

Taking this further, we can see how we can handle complex tokenization.


export default defineNuxtConfig({  app: {    head: {      // dev | My page title | My cool site      titleTemplate: `%envName %titleSeperator %s %titleSeperator %siteName`,      meta: [        {          name: 'description',          // Hi, welcome to the dev v1.3.1 of Nuxt Playground.          content: 'Hi, welcome to the %envName v%app.version of %siteName.',        }      ]    }  },  runtimeConfig: {    public: {      app: {        version: process.env.npm_package_version,      },      titleSeparator: '|',      siteName: 'My cool site',      envName: process.env.NODE_ENV === 'development' ? 'dev' : 'live',    }  }})

The titleSeperator token is unique in that it will be trimmed from the start and end of the title.

Any missing tokens will be replaced with an empty string.



  • Type: boolean
  • Default: true
    Automatically optimise meta tags for SEO.
    It will automatically infer the og:title, og:description when a title and description are set respectively. It will ensure a twitter:card is set to summary_large_image if not set.
    This will do more in the future.

resolveAliases - EXPERIMENTAL

  • Type: boolean
  • Default: false
    Resolve aliases in href and src attributes. This will allow you to load your asset files directly using aliases.
    <script lang="ts" setup>useHead({  link: [    {      rel: 'stylesheet',      href: '~/assets/style.css',    },  ]})</script>


  • Type: string
  • Default: %s
    Template for the og:title meta tag. This will be used when inferring the og:title from title.
    defineNuxtConfig({  unhead: {    ogTitleTemplate: '%pageTitle - %siteName',  },})
    <script lang="ts" setup>useHead({  // og:title will be "My Title - My cool site"  title: 'My Title',})</script>


  • Type: string
  • Default: %s
    Template for the og:description meta tag. This will be used when inferring the og:description from description.
    defineNuxtConfig({  unhead: {    ogDescriptionTemplate: '%s. Check out my cool site',  },})
    <script lang="ts" setup>useHead({  // og:description will be "My Description. Check out my cool site"  meta: [ { name: 'description', content: 'My Description' } ],})</script>



A component to debug your head tags.

DebugHead Component preview
<template>  <DebugHead /></template>



MIT License © 2022-PRESENT Harlan Wilton