Extending Unhead · Unhead

[Unhead Home](https://unhead.unjs.io/ "Home")

- [Docs](https://unhead.unjs.io/docs/solid-js/head/guides/get-started/overview)
- [Tools](https://unhead.unjs.io/tools)
- [Learn](https://unhead.unjs.io/learn/guides/what-is-capo)

[Releases](https://unhead.unjs.io/releases)

Search…```k`` /`

[Unhead on GitHub](https://github.com/unjs/unhead)

[User Guides](https://unhead.unjs.io/docs/solid-js/head/guides/get-started/overview)

[API](https://unhead.unjs.io/docs/solid-js/head/api/get-started/overview)

Solid.js

- [Switch to Solid.js](https://unhead.unjs.io/docs/solid-js/head/guides/advanced/extending-unhead)
- [Switch to TypeScript](https://unhead.unjs.io/docs/typescript/head/guides/advanced/extending-unhead)
- [Switch to Vue](https://unhead.unjs.io/docs/vue/head/guides/advanced/extending-unhead)
- [Switch to React](https://unhead.unjs.io/docs/react/head/guides/advanced/extending-unhead)
- [Switch to Svelte](https://unhead.unjs.io/docs/svelte/head/guides/advanced/extending-unhead)
- [Switch to Angular](https://unhead.unjs.io/docs/angular/head/guides/advanced/extending-unhead)
- [Switch to Nuxt](https://unhead.unjs.io/docs/nuxt/head/guides/advanced/extending-unhead)

v3 (beta)

You're viewing **Unhead v3 beta** documentation.

Head

- [Discord Support](https://discord.com/invite/275MBUBvgP)

- Get Started
  - [Overview](https://unhead.unjs.io/docs/solid-js/head/guides/get-started/overview)
  - [Introduction to Unhead](https://unhead.unjs.io/docs/solid-js/head/guides/get-started/intro-to-unhead)
  - [Starter Recipes](https://unhead.unjs.io/docs/solid-js/head/guides/get-started/starter-recipes)
  - [Installation](https://unhead.unjs.io/docs/solid-js/head/guides/get-started/installation)
  - [Upgrade Guide](https://unhead.unjs.io/docs/solid-js/head/guides/get-started/migration)
- Core Concepts
  - [Titles & Title Templates](https://unhead.unjs.io/docs/solid-js/head/guides/core-concepts/titles)
  - [Tag Sorting & Placement](https://unhead.unjs.io/docs/solid-js/head/guides/core-concepts/positions)
  - [Class & Style Attributes](https://unhead.unjs.io/docs/solid-js/head/guides/core-concepts/class-attr)
  - [Inline Style & Scripts](https://unhead.unjs.io/docs/solid-js/head/guides/core-concepts/inner-content)
  - [Tag Deduplication](https://unhead.unjs.io/docs/solid-js/head/guides/core-concepts/handling-duplicates)
  - [DOM Event Handling](https://unhead.unjs.io/docs/solid-js/head/guides/core-concepts/dom-event-handling)
  - [Script Loading](https://unhead.unjs.io/docs/solid-js/head/guides/core-concepts/loading-scripts)
  - [Reactivity](https://unhead.unjs.io/docs/solid-js/head/guides/core-concepts/reactivity)
  - [StreamingNew](https://unhead.unjs.io/docs/solid-js/head/guides/core-concepts/streaming)
- Advanced
  - [Extending Unhead](https://unhead.unjs.io/docs/solid-js/head/guides/advanced/extending-unhead)
  - [Bundle Optimizations](https://unhead.unjs.io/docs/solid-js/head/guides/advanced/client-only-tags)
  - [Vite Plugin](https://unhead.unjs.io/docs/solid-js/head/guides/advanced/vite-plugin)
- Plugins
  - [Template Params](https://unhead.unjs.io/docs/solid-js/head/guides/plugins/template-params)
  - [Alias Sorting](https://unhead.unjs.io/docs/solid-js/head/guides/plugins/alias-sorting)
  - [Canonical Plugin](https://unhead.unjs.io/docs/solid-js/head/guides/plugins/canonical)
  - [Infer SEO Meta](https://unhead.unjs.io/docs/solid-js/head/guides/plugins/infer-seo-meta-tags)
  - [Minify](https://unhead.unjs.io/docs/solid-js/head/guides/plugins/minify)
  - [Validate](https://unhead.unjs.io/docs/solid-js/head/guides/plugins/validate)

Advanced

# Extending Unhead

[Copy for LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/1.guides/2.advanced/11.extending-unhead.md)

Last updated Apr 5, 2026 by [Harlan Wilton](https://github.com/harlan-zw) in [docs: documentation content audit and formatting improvements (#718)](https://github.com/unjs/unhead/pull/718).

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. **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`

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/solid-js'

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/solid-js'

const head = injectHead()
const tags = 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/solid-js'

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

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

```
import { useHead } from '@unhead/solid-js'

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/solid-js'

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/solid-js'
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/solid-js'

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 {
  'entries:updated': (ctx: Unhead<any>) => HookResult
  'entries:resolve': (ctx: EntryResolveCtx<any>) => SyncHookResult
  'entries:normalize': (ctx: { tags: HeadTag[], entry: HeadEntry<any> }) => SyncHookResult
  'tag:normalise': (ctx: { tag: HeadTag, entry: HeadEntry<any>, resolvedOptions: CreateClientHeadOptions }) => SyncHookResult
  'tags:beforeResolve': (ctx: TagResolveContext) => SyncHookResult
  'tags:resolve': (ctx: TagResolveContext) => SyncHookResult
  'tags:afterResolve': (ctx: TagResolveContext) => SyncHookResult
  'dom:beforeRender': (ctx: DomBeforeRenderCtx) => SyncHookResult
  // ...additional hooks
}
```

Note: `SyncHookResult` is `void` (synchronous only), while `HookResult` is `void | Promise<void>`.

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

[Markdown For LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/1.guides/2.advanced/11.extending-unhead.md)

Did this page help you?

[Script Loading Load external scripts with useScript(). Singleton deduplication, proxy for safe calls, loading triggers, and warmup strategies for performance.](https://unhead.unjs.io/docs/head/guides/core-concepts/loading-scripts) [Bundle Optimizations Reduce bundle size with client-only and server-only tags. Use mode option or import.meta guards for SSR/CSR optimization.](https://unhead.unjs.io/docs/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)

[GitHub](https://github.com/unjs/unhead) [ Discord](https://discord.com/invite/275MBUBvgP)

[ /llms.txt](https://unhead.unjs.io/llms.txt)

[Part of the UnJS ecosystem](https://unjs.io/)

### Articles

- [Announcing Unhead v2](https://unhead.unjs.io/releases/v2)

### Tools

- [Meta Tag Generator](https://unhead.unjs.io/tools/meta-tag-generator)
- [OG Image Generator](https://unhead.unjs.io/tools/og-image-generator)
- [Schema.org Generator](https://unhead.unjs.io/tools/schema-generator)

### Head

- [Overview](https://unhead.unjs.io/docs/solid-js/head/guides/get-started/overview)
- [Introduction to Unhead](https://unhead.unjs.io/docs/solid-js/head/guides/get-started/intro-to-unhead)
- [Starter Recipes](https://unhead.unjs.io/docs/solid-js/head/guides/get-started/starter-recipes)

### Schema.org

- [Introduction](https://unhead.unjs.io/docs/solid-js/schema-org/guides/get-started/overview)

Copyright © 2025-2026 Harlan Wilton - [MIT License](https://github.com/unjs/unhead/blob/main/license)