Skip to main content

​
Usage

The useHead composable allows you to manage your head tags in a programmatic and reactive way, powered by Unhead. It lets you customize the meta tags, links, scripts, and other elements in the <head> section of your HTML document.
[app/app.vue]
<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>
If the data comes from a user or other untrusted source, we recommend you check out useHeadSafe.
The properties of useHead can be dynamic, accepting ref, computed and reactive properties. The meta parameter can also accept a function returning an object to make the entire object reactive.

​
Parameters

​
meta
MaybeComputedRef<MetaObject>
required
An object accepting head metadata properties to customize the page’s <head> section. All properties support reactive values (ref, computed, reactive) or can be a function returning the metadata object.
​
title
string
Sets the page title.
​
titleTemplate
string | ((title?: string) => string)
Configures a dynamic template to customize the page title. Can be a string with %s placeholder or a function.
​
base
Base
Sets the <base> tag for the document.
​
link
Link[]
Array of link objects. Each element is mapped to a <link> tag, where object properties correspond to HTML attributes.
​
meta
Meta[]
Array of meta objects. Each element is mapped to a <meta> tag, where object properties correspond to HTML attributes.
​
style
Style[]
Array of style objects. Each element is mapped to a <style> tag, where object properties correspond to HTML attributes.
​
script
Script[]
Array of script objects. Each element is mapped to a <script> tag, where object properties correspond to HTML attributes.
​
noscript
Noscript[]
Array of noscript objects. Each element is mapped to a <noscript> tag, where object properties correspond to HTML attributes.
​
htmlAttrs
HtmlAttributes
Sets attributes of the <html> tag. Each object property is mapped to the corresponding attribute.
​
bodyAttrs
BodyAttributes
Sets attributes of the <body> tag. Each object property is mapped to the corresponding attribute.

​
Return Values

​
entry
ActiveHeadEntry
An object with methods to update or dispose the head entry.
​
patch
(input: MetaObject) => void
Updates the entry with new input. Will first clear any side effects for previous input.
​
dispose
() => void
Dispose the entry, removing it from the active head. Will queue side effects for removal.

​
Examples

​
Basic Meta Tags

[app/pages/about.vue]
<script setup lang="ts">
useHead({
  title: 'About Us',
  meta: [
    { name: 'description', content: 'Learn more about our company' },
    { property: 'og:title', content: 'About Us' },
    { property: 'og:description', content: 'Learn more about our company' },
  ],
})
</script>

​
Reactive Meta Tags

[app/pages/profile.vue]
<script setup lang="ts">
const profile = ref({ name: 'John Doe' })

useHead({
  title: computed(() => profile.value.name),
  meta: [
    {
      name: 'description',
      content: computed(() => `Profile page for ${profile.value.name}`),
    },
  ],
})
</script>

​
Using a Function for Full Reactivity

[app/pages/dynamic.vue]
<script setup lang="ts">
const count = ref(0)

useHead(() => ({
  title: `Count: ${count.value}`,
  meta: [
    { name: 'description', content: `Current count is ${count.value}` },
  ],
}))
</script>

​
Adding External Scripts and Styles

[app/pages/external.vue]
<script setup lang="ts">
useHead({
  link: [
    {
      rel: 'stylesheet',
      href: 'https://cdn.example.com/styles.css',
    },
  ],
  script: [
    {
      src: 'https://cdn.example.com/script.js',
      async: true,
    },
  ],
})
</script>

​
Body and HTML Attributes

[app/pages/themed.vue]
<script setup lang="ts">
const isDark = ref(true)

useHead({
  htmlAttrs: {
    lang: 'en',
    class: computed(() => isDark.value ? 'dark' : 'light'),
  },
  bodyAttrs: {
    class: 'themed-page',
  },
})
</script>

​
Type

export function useHead (
  meta: MaybeComputedRef<MetaObject>
): ActiveHeadEntry<UseHeadInput>

interface MetaObject {
  title?: string
  titleTemplate?: string | ((title?: string) => string)
  base?: Base
  link?: Link[]
  meta?: Meta[]
  style?: Style[]
  script?: Script[]
  noscript?: Noscript[]
  htmlAttrs?: HtmlAttributes
  bodyAttrs?: BodyAttributes
}

interface ActiveHeadEntry<Input> {
  patch: (input: Input) => void
  dispose: () => void
}