useHead

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

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.

string

Sets the page title.

string | ((title?: string) => string)

Configures a dynamic template to customize the page title. Can be a string with %s placeholder or a function.

Base

Sets the <base> tag for the document.

Link[]

Array of link objects. Each element is mapped to a <link> tag, where object properties correspond to HTML attributes.

Meta[]

Array of meta objects. Each element is mapped to a <meta> tag, where object properties correspond to HTML attributes.

Style[]

Array of style objects. Each element is mapped to a <style> tag, where object properties correspond to HTML attributes.

Script[]

Array of script objects. Each element is mapped to a <script> tag, where object properties correspond to HTML attributes.

Noscript[]

Array of noscript objects. Each element is mapped to a <noscript> tag, where object properties correspond to HTML attributes.

HtmlAttributes

Sets attributes of the <html> tag. Each object property is mapped to the corresponding attribute.

BodyAttributes

Sets attributes of the <body> tag. Each object property is mapped to the corresponding attribute.

Return Values

ActiveHeadEntry

An object with methods to update or dispose the head entry.

(input: MetaObject) => void

Updates the entry with new input. Will first clear any side effects for previous input.

() => 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
}

Components

Composables

Utils

Commands

Nuxt Config

Kit API

Usage

Parameters

Return Values

Examples

Basic Meta Tags

Reactive Meta Tags

Using a Function for Full Reactivity

Adding External Scripts and Styles

Body and HTML Attributes

Type

​Usage

​Parameters

​Return Values

​Examples

​Basic Meta Tags

​Reactive Meta Tags

​Using a Function for Full Reactivity

​Adding External Scripts and Styles

​Body and HTML Attributes

​Type

Usage

Parameters

Return Values

Examples

Basic Meta Tags

Reactive Meta Tags

Using a Function for Full Reactivity

Adding External Scripts and Styles

Body and HTML Attributes

Type