Package Exports

@vueuse/head
@vueuse/head/dist/index.js
@vueuse/head/dist/index.mjs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@vueuse/head) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@vueuse/head

A Vue composition API to manage your document head.

Created by egoist, maintained by harlan-zw
_{💛 Support ongoing development by sponsoring us.}
_{Follow 🐦 @harlan_zw for updates • Join Discord for support}

Features

✨ Best practice head with deduping and default ordering
🤖 SSR ready
🔨 Deeply reactive with computed getter support
🌳 Fully typed document <head> with inline doc

Installation

npm i @vueuse/head
# Or Yarn
yarn add @vueuse/head

Requires vue >= v3 or >=2.7

Ecosystem Examples

Usage

import { createApp } from "vue"
import { createHead } from "@vueuse/head"

const app = createApp()
const head = createHead()

app.use(head)

app.mount("#app")

Manage head with the composition API useHead in your component:

<script>
import { defineComponent, computed, reactive } from "vue"
import { useHead } from "@vueuse/head"

export default defineComponent({
  setup() {
    const siteData = reactive({
      title: `My website`,
      description: `My beautiful website`,
    })

    useHead({
      // Can be static or computed
      title: computed(() => siteData.title),
      meta: [
        {
          name: `description`,
          content: computed(() => siteData.description),
        },
      ],
    })
  },
})
</script>

Server-side rendering

import { renderToString } from "@vue/server-renderer"
import { renderHeadToString } from "@vueuse/head"

const appHTML = await renderToString(yourVueApp)

// `head` is created from `createHead()`
const { headTags, htmlAttrs, bodyAttrs, bodyTags } = renderHeadToString(head)

const finalHTML = `
<html${htmlAttrs}>

  <head>
    ${headTags}
  </head>

  <body${bodyAttrs}>
    <div id="app">${appHTML}</div>
    ${bodyTags}
  </body>

</html>
`

API

`createHead(head?: HeadObject | Ref<HeadObject>)`

Create the head manager instance.

`useHead(head: HeadObject | Ref<HeadObject>)`

interface HeadObject {
  title?: MaybeRef<string>
  titleTemplate?: MaybeRef<string> | ((title?: string) => string)
  meta?: MaybeRef<HeadAttrs[]>
  link?: MaybeRef<HeadAttrs[]>
  base?: MaybeRef<HeadAttrs>
  style?: MaybeRef<HeadAttrs[]>
  script?: MaybeRef<HeadAttrs[]>
  noscript?: MaybeRef<HeadAttrs[]>
  htmlAttrs?: MaybeRef<HeadAttrs>
  bodyAttrs?: MaybeRef<HeadAttrs>
}

interface HeadAttrs {
  [attrName: string]: any
}

For meta tags, we use name and property to prevent duplicated tags, you can instead use the key attribute if the same name or property is allowed:

useHead({
  meta: [
    {
      property: "og:locale:alternate",
      content: "zh",
      key: "zh",
    },
    {
      property: "og:locale:alternate",
      content: "en",
      key: "en",
    },
  ],
})

To render tags at the end of the <body>, set body: true in a HeadAttrs Object.

useHead({
  script: [
    {
      children: `console.log('Hello world!')`,
      body: true,
    },
  ],
})

To set the textContent of an element, use the children attribute:

useHead({
  style: [
    {
      children: `body {color: red}`,
    },
  ],
  noscript: [
    {
      children: `Javascript is required`,
    },
  ],
})

useHead also takes reactive object or ref as the argument, for example:

const head = reactive({ title: "Website Title" })
useHead(head)

const title = ref("Website Title")
useHead({ title })

Render Priority

⚠️ Experimental feature Only available when rendering SSR.

To set the render priority of a tag you can use the renderPriority attribute:

useHead({
  script: [
    {
      src: "/not-important-script.js",
    },
  ],
})

useHead({
  script: [
    // will render first
    {
      src: "/very-important-script.js",
      renderPriority: 1 // default is 10, so will be first
    },
  ],
})

The following special tags have default priorities:

-2 <meta charset ...>
-1 <base>
0 <meta http-equiv="content-security-policy" ...>

All other tags have a default priority of 10: ,