Nuxt head management powered by Unhead
Nuxt head tag management is powered by Unhead. It provides sensible defaults, several powerful composables and numerous configuration options to manage your app's head and SEO meta tags.
Nuxt · Getting started · all subjects
seo-meta
31 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Set static head tags in nuxt.config.ts app.head
Providing an app.head property in nuxt.config.ts allows you to statically customize the head for your entire app. This method does not allow you to provide reactive data. It is good practice to set tags here that won't change, such as site title default, language, and favicon.
Example: Configure app.head in nuxt.config.ts
export default defineNuxtConfig({ app: { head: { title: 'Nuxt', // default fallback title htmlAttrs: { lang: 'en', }, link: [ { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' }, ], }, }, })
CDN URL resolution for favicon in app.head
When you set app.cdnURL, assets in the public/ directory (including favicon.ico) are served from that CDN. Nuxt resolves public assets against cdnURL, falling back to app.baseURL. However, a static app.head link such as href: '/favicon.ico' is a literal path and is not resolved against cdnURL. To point the favicon at the resolved location, build the href from runtime config with useHead() in app.vue.
Example: Resolve favicon with runtime config in app.vue
<script setup lang="ts"> const { cdnURL, baseURL } = useRuntimeConfig().app useHead({ link: [ { rel: 'icon', type: 'image/x-icon', href: `${cdnURL || baseURL}favicon.ico` }, ], }) </script>
Default meta tags in Nuxt
Nuxt provides these default tags: viewport with value 'width=device-width, initial-scale=1' and charset with value 'utf-8'. Most sites won't need to override these defaults, but you can update them using keyed shortcuts in app.head.
Example: Override default meta tags
export default defineNuxtConfig({ app: { head: { // update Nuxt defaults charset: 'utf-16', viewport: 'width=device-width, initial-scale=1, maximum-scale=1', }, }, })
useHead composable for reactive head tags
The useHead composable function supports reactive input, allowing you to manage your head tags programmatically. You can provide reactive data such as refs, computed values, and getters.
Example: useHead with reactive data
<script setup lang="ts"> useHead({ title: 'My App', meta: [ { name: 'description', content: 'My amazing site.' }, ], bodyAttrs: { class: 'test', }, script: [{ innerHTML: 'console.log(\'Hello world\')' }], }) </script>
useSeoMeta composable for type-safe SEO tags
The useSeoMeta composable lets you define your site's SEO meta tags as an object with full type safety. This helps you avoid typos and common mistakes, such as using name instead of property.
Example: useSeoMeta for SEO meta tags
<script setup lang="ts"> useSeoMeta({ title: 'My Amazing Site', ogTitle: 'My Amazing Site', description: 'This is my amazing site, let me tell you all about it.', ogDescription: 'This is my amazing site, let me tell you all about it.', ogImage: 'https://example.com/image.png', twitterCard: 'summary_large_image', }) </script>
Head management components in Nuxt
Nuxt provides these components for head management: Title, Base, NoScript, Style, Meta, Link, Body, Html, and Head. These are capitalized to avoid using invalid native HTML tags. Head and Body can accept nested meta tags for aesthetic reasons but this does not affect where the nested meta tags are rendered in the final HTML. It is suggested to wrap components in either a Head or Html component as tags will be deduped more intuitively.
Example: Head management components in template
<script setup lang="ts"> const title = ref('Hello World') </script> <template> <div> <Head> <Title>{{ title }}</Title> <Meta name="description" :content="title" /> <Style> body { background-color: green; } </Style> </Head> <h1>{{ title }}</h1> </div> </template>
Apply key attribute to Head component for duplicate tags
If you need to duplicate tags across client-server boundaries, apply a key attribute on the Head component.
MetaObject interface for useHead and app.head
interface MetaObject { title?: string titleTemplate?: string | ((title?: string) => string) templateParams?: Record<string, string | Record<string, string>> base?: Base link?: Link[] meta?: Meta[] style?: Style[] script?: Script[] noscript?: Noscript[] htmlAttrs?: HtmlAttributes bodyAttrs?: BodyAttributes }
Reactivity with useHead and useSeoMeta
Reactivity is supported on all properties by providing a computed value, a getter, or a reactive object. This works with useHead, useSeoMeta, and Meta components.
Example: Reactive description with useHead
<script setup lang="ts"> const description = ref('My amazing site.') useHead({ meta: [ { name: 'description', content: description }, ], }) </script>
Example: Reactive description with useSeoMeta
<script setup lang="ts"> const description = ref('My amazing site.') useSeoMeta({ description, }) </script>
Example: Reactive Meta component in template
<script setup lang="ts"> const description = ref('My amazing site.') </script> <template> <div> <Meta name="description" :content="description" /> </div> </template>
titleTemplate feature for dynamic page titles
You can use the titleTemplate option to provide a dynamic template for customizing the title of your site. The titleTemplate can either be a string, where %s is replaced with the title, or a function. If you want to use a function, this cannot be set in nuxt.config and should instead be set within app.vue where it will apply to all pages.
Example: titleTemplate as function in useHead
<script setup lang="ts"> useHead({ titleTemplate: (titleChunk) => { return titleChunk ? `${titleChunk} - Site Title` : 'Site Title' }, }) </script>
Example: titleTemplate as string in useHead
<script setup lang="ts"> useHead({ // as a string, // where `%s` is replaced with the title titleTemplate: '%s - Site Title', }) </script>
templateParams for additional title placeholders
You can use templateParams to provide additional placeholders in your titleTemplate besides the default %s. This allows for more dynamic title generation.
Example: templateParams with custom placeholders
<script setup lang="ts"> useHead({ titleTemplate: (titleChunk) => { return titleChunk ? `${titleChunk} %separator %siteName` : '%siteName' }, templateParams: { siteName: 'Site Title', separator: '-', }, }) </script>
tagPosition option to place tags at body close
You can use the tagPosition: 'bodyClose' option on applicable tags to append them to the end of the body tag. Valid options are: 'head' | 'bodyClose' | 'bodyOpen'.
Example: tagPosition for script tag placement
<script setup lang="ts"> useHead({ script: [ { src: 'https://third-party-script.com', // valid options are: 'head' | 'bodyClose' | 'bodyOpen' tagPosition: 'bodyClose', }, ], }) </script>
Use definePageMeta with useHead for route-based metadata
Within app/pages/ directory, you can use definePageMeta along with useHead to set metadata based on the current route. definePageMeta is extracted at build time via a macro, so it can't be set dynamically.
Example: definePageMeta for page title
<script setup lang="ts"> definePageMeta({ title: 'Some Page', }) </script>
Example: Access route meta in layout with useHead
<script setup lang="ts"> const route = useRoute() useHead({ meta: [{ property: 'og:title', content: `App Name - ${route.meta.title}` }], }) </script>
Example: External CSS with Google Fonts using useHead
<script setup lang="ts"> useHead({ link: [ { rel: 'preconnect', href: 'https://fonts.googleapis.com', }, { rel: 'stylesheet', href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', crossorigin: '', }, ], }) </script>
Example: External CSS with Google Fonts using Link component
<template> <div> <Link rel="preconnect" href="https://fonts.googleapis.com" /> <Link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" crossorigin="" /> </div> </template>