---
title: "Extending Unhead · v2 · Unhead"
meta:
  "og:description": "Learn how to extend Unhead with hooks and plugins to create custom functionality"
  "og:title": "Extending Unhead · v2 · Unhead"
  description: "Learn how to extend Unhead with hooks and plugins to create custom functionality"
---

**Advanced**

# **Extending Unhead**

**On this page **

- [Introduction](#introduction)
- [Understanding the Architecture](#understanding-the-architecture)
- [Accessing Head State](#accessing-head-state)
- [Creating Custom Composables](#creating-custom-composables)
- [Building Plugins](#building-plugins)
- [Common Use Cases](#common-use-cases)
- [Best Practices](#best-practices)
- [API Reference](#api-reference)

## [Introduction](#introduction)

Unhead is designed with extensibility in mind, providing lower-level primitives that can be composed to create powerful functionality. This guide explores how to extend Unhead using hooks and plugins to meet your specific requirements.

## [Understanding the Architecture](#understanding-the-architecture)

Unhead uses a hooks-based architecture powered by [**unjs/hookable**](https://github.com/unjs/hookable), allowing you to tap into different parts of the head tag management lifecycle. This enables you to create custom features without modifying the core library.

### [Hook Execution Sequence](#hook-execution-sequence)

Understanding the order in which hooks are executed is important for creating plugins that work well together. Here is the typical flow:

1. **Initialization**: `init`
2. **Entry Processing**:

- `entries:updated`
- `entries:resolve`
- For each entry: `entries:normalize`

1. **Tag Processing**:

- For each tag: `tag:normalise`
- `tags:beforeResolve`
- `tags:resolve`
- `tags:afterResolve`

1. **Client-side Rendering**:

- `dom:beforeRender`
- For each tag: `dom:renderTag`
- `dom:rendered`

1. **Server-side Rendering**:

- `ssr:beforeRender`
- `ssr:render`
- `ssr:rendered`

1. **Script Management**:

- When applicable: `script:updated`

### [Available Hooks](#available-hooks)

Unhead provides several hooks you can use to extend functionality:

```
import { createHead, useHead } from 'unhead'

const head = createHead({
  hooks: {
    'entries:resolve': (ctx) => {
      // Called when entries need to be resolved to tags
    },
    'tags:resolve': (ctx) => {
      // Called when tags are being resolved for rendering
    },
    'tag:normalise': (ctx) => {
      // Called when a tag is being normalized
    },
    'tag:generated': (ctx) => {
      // Called after a tag has been generated
    }
    // See full list in the API reference
  }
})
```

## [Accessing Head State](#accessing-head-state)

The recommended way to access the head state is through the `resolveTags` function:

```
import { injectHead, useHead } from 'unhead'

const head = injectHead()
const tags = await head.resolveTags()

// Now you can inspect or manipulate the tags
console.log(tags)
```

This gives you access to the fully processed tags that would be rendered to the DOM.

## [Creating Custom Composables](#creating-custom-composables)

Unhead's composables like `useHead()` and `useSeoMeta()` are built on top of primitive APIs. You can create your own composables for specific use cases.

### [Example: Creating useTitle Composable](#example-creating-usetitle-composable)

```
import { useHead } from 'unhead'

export function useTitle(title: string, options = {}) {
  return useHead({
    title,
  }, options)
}
```

### [Example: Creating useBodyClass Composable](#example-creating-usebodyclass-composable)

```
import { useHead } from 'unhead'

export function useBodyClass(classes: string | string[]) {
  const classList = Array.isArray(classes) ? classes : [classes]

  return useHead({
    bodyAttrs: {
      class: classList.join(' ')
    }
  })
}
```

## [Building Plugins](#building-plugins)

For more complex extensions, you can create plugins that hook into multiple parts of Unhead's lifecycle.

### [Example: Custom Deduplication Plugin](#example-custom-deduplication-plugin)

```
import { defineHeadPlugin } from 'unhead'

export const customDedupePlugin = defineHeadPlugin({
  hooks: {
    'tags:resolve': (ctx) => {
      // Custom logic to deduplicate tags
      ctx.tags = deduplicateTagsWithCustomLogic(ctx.tags)
    }
  }
})

// Usage
const head = createHead({
  plugins: [
    customDedupePlugin()
  ]
})
```

## [Common Use Cases](#common-use-cases)

### [Example: Tailwind Class Deduplication](#example-tailwind-class-deduplication)

This example shows how to deduplicate Tailwind CSS classes using `tailwind-merge`:

```
import { defineHeadPlugin } from 'unhead'
import { twMerge } from 'tailwind-merge'

export const tailwindMergePlugin = defineHeadPlugin({
  hooks: {
    'tags:resolve': (ctx) => {
      // Find body tags with class attributes
      ctx.tags.forEach((tag) => {
        if (tag.tag === 'bodyAttrs' && tag.props.class) {
          // Deduplicate classes with tailwind-merge
          tag.props.class = twMerge(tag.props.class)
        }
      })
    }
  }
})
```

### [Example: Custom MetaInfo Provider](#example-custom-metainfo-provider)

Create a plugin that pulls meta information from a global store:

```
import { defineHeadPlugin } from 'unhead'

export const storeMetaPlugin = defineHeadPlugin({
  hooks: {
    'entries:resolve': (ctx) => {
      // Add entries from a store
      const storeMetaInfo = getMetaFromStore()
      ctx.entries.push(storeMetaInfo)
    }
  }
})
```

## [Best Practices](#best-practices)

When extending Unhead:

- Keep extensions focused on a single concern
- Use typed hooks for better developer experience
- Document your extensions for team usage
- Consider performance implications in your hooks
- Test extensions with a variety of input cases

## [API Reference](#api-reference)

For a complete list of available hooks and their signatures, refer to the hooks definitions in the source code:

```
// From packages/unhead/src/types/hooks.ts
export interface HeadHooks {
  'init': () => void
  'entries:resolve': (ctx: CallbackParams<'entries:resolve'>) => void | Promise<void>
  'tags:resolve': (ctx: CallbackParams<'tags:resolve'>) => void | Promise<void>
  'tag:normalise': (ctx: TagAugmentation) => void | Promise<void>
  'tag:resolve': (ctx: CallbackParams<'tag:resolve'>) => void | Promise<void>
  'tag:validate': (ctx: TagAugmentation) => void | Promise<void>
  'tag:generated': (ctx: TagAugmentation) => void | Promise<void>
  // ...additional hooks
}
```

[Edit this page](https://github.com/unjs/unhead/edit/v2.1.2/docs/v2/head/1.guides/2.advanced/11.extending-unhead.md)

**Did this page help you? **

[**Script Loading** Learn how to efficiently load and manage scripts with Unhead's useScript composable](https://unhead.unjs.io/docs/v2/head/guides/core-concepts/loading-scripts) [**Bundle Optimizations** Optimize your application bundle size with client and server-side rendering strategies](https://unhead.unjs.io/docs/v2/head/guides/advanced/client-only-tags)

**On this page **

- [Introduction](#introduction)
- [Understanding the Architecture](#understanding-the-architecture)
- [Accessing Head State](#accessing-head-state)
- [Creating Custom Composables](#creating-custom-composables)
- [Building Plugins](#building-plugins)
- [Common Use Cases](#common-use-cases)
- [Best Practices](#best-practices)
- [API Reference](#api-reference)