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 with augmentation support (powered by zhead)

Installation

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

Requires vue >= v3 or >=2.7

For instructions on setting up @vueuse/head as an integration, see integration.

API

`useHead(head: MaybeComputedRef<HeadObject>)`

Used to modify the head of the document. You can call this function in any page or component.

All values are reactive and support ref and computed getter syntax.

To provide inner content you should use the children attribute.

Example

const myPage = ref({
  description: 'This is my page',
})
const title = ref('title')
useHead({
  // ref syntax
  title,
  meta: [
    // computer getter syntax  
    { name: 'description', content: () => myPage.value.description },
  ],
  style: [
    { type: 'text/css', children: 'body { background: red; }' },
  ],
  script: [
    // primitive values are also fine
    { 
      src: 'https://example.com/script.js',
      defer: true
    },
  ],
})

Types

You can check @zhead/schema for full types.

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

`useHeadSafe(head: MaybeComputedRef<HeadObject>)`

Has the same functionality as useHead but encodes values to prevent XSS. This is useful for inserting untrusted data from third-parties.

useHeadSafe({
  bodyAttrs: {
    onfocus: 'alert("hello")',
  },
  script: [
    {
      children: 'alert("hello world")',
    },
  ],
})

Deduping

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",
    },
  ],
})

Body Tags

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,
    },
  ],
})

Text Content

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

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