Plugins

On this page

defineHeadPlugin
Custom Composables
Plugin Type
See Also

Unhead uses a hook-based architecture. Plugins can inspect or modify entry resolution, resolved tags, DOM rendering, and server rendering.

defineHeadPlugin

defineHeadPlugin() is a type helper for plugin objects and setup functions. An object plugin needs a stable key and may register hooks.

import { defineHeadPlugin } from 'unhead/plugins'

export const myPlugin = defineHeadPlugin({
  key: 'my-plugin',
  hooks: {
    'tags:resolve': (ctx) => {
      // Modify ctx.tags before rendering.
    },
  },
})

Plugins can also be setup functions that receive the Unhead instance. Pass a static key as the second argument when setup can have side effects; this lets Unhead deduplicate the plugin before invoking it again.

import { defineHeadPlugin } from 'unhead/plugins'
import { resolveTags } from 'unhead/utils'

export const myPlugin = defineHeadPlugin(head => ({
  key: 'my-plugin',
  hooks: {
    'entries:updated': () => {
      const tags = resolveTags(head)
      console.log('Current tags:', tags)
    },
  },
}), 'my-plugin')

Registering Plugins

Pass plugins when creating the head instance, or add them later with head.use().

import { createHead } from 'unhead/client'

const head = createHead({
  plugins: [myPlugin],
})

// or later
head.use(myPlugin)

Custom Composables

You can wrap your framework's useHead() composable to create helpers for recurring patterns.

import { useHead } from 'unhead'

export function useBodyClass(classes: string | string[]) {
  const classList = Array.isArray(classes) ? classes : [classes]
  return useHead(unheadInstance, {
    bodyAttrs: {
      class: classList.join(' '),
    },
  })
}

Plugin Type

type HeadPluginInput =
  | (HeadPluginOptions & { key: string })
  | (((head: Unhead) => HeadPluginOptions & { key: string }) & {
      key?: string
    })

interface HeadPluginOptions extends CreateHeadOptions {
  hooks?: Record<string, (...args: any[]) => any>
}

HeadPluginOptions extends the core head-creation options at the type level. Plugin registration itself consumes the plugin's key and hooks; setup functions can use the supplied head instance to push entries or wrap instance methods before returning those hooks.

Plugins

defineHeadPlugin

Registering Plugins

Custom Composables

Plugin Type

See Also