tags:beforeResolve Hook · Unhead

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

- [Docs](https://unhead.unjs.io/docs/typescript/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/typescript/head/guides/get-started/overview)

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

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

TypeScript

- [Switch to TypeScript](https://unhead.unjs.io/docs/typescript/head/api/hooks/tags-before-resolve)
- [Switch to Vue](https://unhead.unjs.io/docs/vue/head/api/hooks/tags-before-resolve)
- [Switch to React](https://unhead.unjs.io/docs/react/head/api/hooks/tags-before-resolve)
- [Switch to Svelte](https://unhead.unjs.io/docs/svelte/head/api/hooks/tags-before-resolve)
- [Switch to Solid.js](https://unhead.unjs.io/docs/solid-js/head/api/hooks/tags-before-resolve)
- [Switch to Angular](https://unhead.unjs.io/docs/angular/head/api/hooks/tags-before-resolve)
- [Switch to Nuxt](https://unhead.unjs.io/docs/nuxt/head/api/hooks/tags-before-resolve)

v3 (stable)

Head

- [Discord Support](https://discord.com/invite/275MBUBvgP)
- [TypeScript Playground](https://stackblitz.com/edit/github-hhxywsb5)

- Get Started
  - [Overview](https://unhead.unjs.io/docs/typescript/head/api/get-started/overview)
- Composables
  - [`useHead()`](https://unhead.unjs.io/docs/typescript/head/api/composables/use-head)
  - [`useHeadSafe()`](https://unhead.unjs.io/docs/typescript/head/api/composables/use-head-safe)
  - [`useSeoMeta()`](https://unhead.unjs.io/docs/typescript/head/api/composables/use-seo-meta)
  - [`useScript()`](https://unhead.unjs.io/docs/typescript/head/api/composables/use-script)
- Hooks
  - [entries:updated](https://unhead.unjs.io/docs/typescript/head/api/hooks/entries-updated)
  - [entries:resolve](https://unhead.unjs.io/docs/typescript/head/api/hooks/entries-resolve)
  - [entries:normalize](https://unhead.unjs.io/docs/typescript/head/api/hooks/entries-normalize)
  - [tag:normalise](https://unhead.unjs.io/docs/typescript/head/api/hooks/tag-normalise)
  - [tags:beforeResolve](https://unhead.unjs.io/docs/typescript/head/api/hooks/tags-before-resolve)
  - [tags:resolve](https://unhead.unjs.io/docs/typescript/head/api/hooks/tags-resolve)
  - [tags:afterResolve](https://unhead.unjs.io/docs/typescript/head/api/hooks/tags-after-resolve)
  - [dom:beforeRender](https://unhead.unjs.io/docs/typescript/head/api/hooks/dom-before-render)
  - [ssr:beforeRender](https://unhead.unjs.io/docs/typescript/head/api/hooks/ssr-before-render)
  - [ssr:render](https://unhead.unjs.io/docs/typescript/head/api/hooks/ssr-render)
  - [ssr:rendered](https://unhead.unjs.io/docs/typescript/head/api/hooks/ssr-rendered)
  - [script:updated](https://unhead.unjs.io/docs/typescript/head/api/hooks/script-updated)
- [Plugins](https://unhead.unjs.io/docs/head/api/plugins)

Hooks

# tags:beforeResolve Hook

[Copy for LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/7.api/hooks/06.tags-before-resolve.md)

Last updated Jan 19, 2026 by [Harlan Wilton](https://github.com/harlan-zw) in [docs: sync](https://github.com/unjs/unhead/commit/d2f86454774aa60706628b46a850653e1e4d56d9).

On this page

- [Lifecycle Position](#lifecycle-position)
- [Hook Signature](#hook-signature)
- [Usage Example](#usage-example)
- [Use Cases](#use-cases)

The `tags:beforeResolve` hook is called just before the tag resolution process begins. This hook provides access to all tags that have been collected from entries and allows for bulk modifications before the main resolution process.

## [Lifecycle Position](#lifecycle-position)

This hook runs after [`tag:normalise`](https://unhead.unjs.io/docs/head/api/hooks/tag-normalise) and before [`tags:resolve`](https://unhead.unjs.io/docs/head/api/hooks/tags-resolve).

## [Hook Signature](#hook-signature)

```
export interface Hook {
  'tags:beforeResolve': (ctx: TagResolveContext) => HookResult
}
```

### [Parameters](#parameters)

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | `TagResolveContext` | Context object with the collection of tags |

The `TagResolveContext` interface is defined as:

```
interface TagResolveContext {
  tagMap: Map<string, HeadTag>
  tags: HeadTag[]
}
```

### [Returns](#returns)

`HookResult` which is either `void` or `Promise<void>`

## [Usage Example](#usage-example)

```
import { createHead } from 'unhead'

const head = createHead({
  hooks: {
    'tags:beforeResolve': (ctx) => {
      // Log all tags before resolution
      console.log(\`Processing ${ctx.tags.length} tags before resolution\`)

      // Add a tag that should be included in all pages
      ctx.tags.push({
        tag: 'meta',
        props: {
          name: 'generator',
          content: 'Unhead'
        }
      })
    }
  }
})
```

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

### [Pre-processing Tags](#pre-processing-tags)

You can use this hook to pre-process tags before the main resolution:

```
import { defineHeadPlugin } from 'unhead'

export const tagsPreprocessPlugin = defineHeadPlugin({
  hooks: {
    'tags:beforeResolve': (ctx) => {
      // Sort tags by priority before resolution
      ctx.tags.sort((a, b) => {
        const aPriority = a.tagPriority === 'high'
          ? 0
          : a.tagPriority === 'critical' ? -1 : 1
        const bPriority = b.tagPriority === 'high'
          ? 0
          : b.tagPriority === 'critical' ? -1 : 1
        return aPriority - bPriority
      })
    }
  }
})
```

### [Adding Global Tags](#adding-global-tags)

This hook is ideal for adding tags that should be present on all pages:

```
import { defineHeadPlugin } from 'unhead'

export const globalTagsPlugin = defineHeadPlugin({
  hooks: {
    'tags:beforeResolve': (ctx) => {
      // Add global meta tags
      const globalTags = [
        {
          tag: 'meta',
          props: {
            charset: 'utf-8'
          }
        },
        {
          tag: 'meta',
          props: {
            name: 'viewport',
            content: 'width=device-width, initial-scale=1'
          }
        },
        {
          tag: 'link',
          props: {
            rel: 'icon',
            href: '/favicon.ico'
          }
        }
      ]

      ctx.tags.push(...globalTags)
    }
  }
})
```

### [Filtering Tags Based on Environment](#filtering-tags-based-on-environment)

Filter or modify tags based on the current environment:

```
import { defineHeadPlugin } from 'unhead'

export const environmentFilterPlugin = defineHeadPlugin((head) => {
  return {
    hooks: {
      'tags:beforeResolve': (ctx) => {
        const isProduction = process.env.NODE_ENV === 'production'

        // Remove development-only tags in production
        if (isProduction) {
          ctx.tags = ctx.tags.filter((tag) => {
            // Remove development-specific meta tags
            if (tag.tag === 'meta' && tag.props.name === 'robots'
              && tag.props.content === 'noindex, nofollow') {
              return false
            }

            // Remove debug scripts
            if (tag.tag === 'script' && tag.props['data-debug']) {
              return false
            }

            return true
          })
        }
      }
    }
  }
})
```

[Edit this page](https://github.com/unjs/unhead/edit/main/docs/head/7.api/hooks/06.tags-before-resolve.md)

[Markdown For LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/7.api/hooks/06.tags-before-resolve.md)

Did this page help you?

[tag:normalise Hook for processing individual head tags. Apply security attributes, transform tags per environment, and handle custom attributes.](https://unhead.unjs.io/docs/head/api/hooks/tag-normalise) [tags:resolve Main tag resolution hook for deduplication, transformation, and template parameter processing. Modify all tags before rendering.](https://unhead.unjs.io/docs/head/api/hooks/tags-resolve)

On this page

- [Lifecycle Position](#lifecycle-position)
- [Hook Signature](#hook-signature)
- [Usage Example](#usage-example)
- [Use Cases](#use-cases)

[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/)

### Head Management

- [Getting Started](https://unhead.unjs.io/docs/typescript/head/guides/get-started/overview)
- [useHead](https://unhead.unjs.io/docs/typescript/head/api/composables/use-head)
- [useSeoMeta](https://unhead.unjs.io/docs/typescript/head/api/composables/use-seo-meta)
- [useHeadSafe](https://unhead.unjs.io/docs/typescript/head/api/composables/use-head-safe)
- [useScript](https://unhead.unjs.io/docs/typescript/head/api/composables/use-script)

### Schema.org

- [Getting Started](https://unhead.unjs.io/docs/typescript/schema-org/guides/get-started/overview)
- [useSchemaOrg](https://unhead.unjs.io/docs/typescript/schema-org/api/composables/use-schema-org)
- [Nodes](https://unhead.unjs.io/docs/typescript/schema-org/guides/core-concepts/nodes)
- [Recipes](https://unhead.unjs.io/docs/typescript/schema-org/guides/recipes/identity)

### Guides

- [Titles](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/titles)
- [Streaming SSR](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/streaming)
- [DOM Events](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/dom-event-handling)
- [Plugins](https://unhead.unjs.io/docs/typescript/head/guides/plugins/template-params)

### 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)
- [Capo.js Analyzer](https://unhead.unjs.io/tools/capo-analyzer)

### Articles

- [What is Capo.js?](https://unhead.unjs.io/learn/guides/what-is-capo)

### Research

- [State of <head> in 2026](https://unhead.unjs.io/learn/research/state-of-head-2026)
- [Streaming Head Performance](https://unhead.unjs.io/learn/research/streaming-head-performance)
- [Capo.js Performance Research](https://unhead.unjs.io/learn/research/capo-performance-research)

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