unhead
Go to documentationExperimental features for Nuxt SEO / head management.
△ nuxt-unhead
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.
Features
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
andsrc
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)
Background
This module was built to test bug fixes as well as experimental new features which may land into the Nuxt core.
Install
npm install --save-dev nuxt-unhead# Using yarnyarn add --dev nuxt-unhead
Setup
nuxt.config.ts
export default defineNuxtConfig({ modules: [ 'nuxt-unhead', ],})
Module Configuration
Config key: unhead
nuxt.config.ts
export default defineNuxtConfig({ modules: ['nuxt-unhead'], unhead: { // config (see below) }, //...})
Usage
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.
nuxt.config.ts
export default defineNuxtConfig({ runtimeConfig: { public: { siteName: 'My cool site', titleSeparator: '|', } },})
Taking this further, we can see how we can handle complex tokenization.
nuxt.config.ts
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.
Config
seoOptimise
- Type:
boolean
- Default:
true
Automatically optimise meta tags for SEO.
It will automatically infer theog:title
,og:description
when a title and description are set respectively. It will ensure atwitter:card
is set tosummary_large_image
if not set.
This will do more in the future.
resolveAliases - EXPERIMENTAL
- Type:
boolean
- Default:
false
Resolve aliases inhref
andsrc
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>
ogTitleTemplate
- Type:
string
- Default:
%s
Template for theog: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>
ogDescriptionTemplate
- Type:
string
- Default:
%s
Template for theog: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>
Components
DebugHead
A component to debug your head tags.

<template> <DebugHead /></template>
Sponsors
License
MIT License © 2022-PRESENT Harlan Wilton