gil-wiki/use-head.md at main

Files

- CLAUDE.md 운영 규칙
- wiki/ 정리된 지식 페이지 (Nuxt + Claude Code)
- raw/ 원본 자료
- reference/ Nuxt 4.x 공식 문서

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-13 00:31:51 +09:00

5.2 KiB

Raw Permalink Blame History

title, description, links

title

description

links

useHead

useHead customizes the head properties of individual pages of your Nuxt app.

label	icon	to	size
Source	i-simple-icons-github	https://github.com/unjs/unhead/blob/main/packages/vue/src/composables.ts	xs

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.

<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>

::warning If the data comes from a user or other untrusted source, we recommend you check out useHeadSafe. ::

::note 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. ::

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> {
  /**
   * Updates the entry with new input.
   *
   * Will first clear any side effects for previous input.
   */
  patch: (input: Input) => void
  /**
   * Dispose the entry, removing it from the active head.
   *
   * Will queue side effects for removal.
   */
  dispose: () => void
}

See @unhead/schema for more detailed types.

Parameters

meta: 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.

Property	Type	Description
`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

This composable does not return any value. It registers the head metadata with Unhead, which manages the actual DOM updates.

Examples

Basic Meta Tags

<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

<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

<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

<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

<script setup lang="ts">
const isDark = ref(true)

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

:read-more{to="/docs/4.x/getting-started/seo-meta"}

5.2 KiB Raw Permalink Blame History