---
title: "tag:normalise Hook"
description: "Hook for processing individual head tags. Apply security attributes, transform tags per environment, and handle custom attributes."
canonical_url: "https://unhead.unjs.io/docs/head/api/hooks/tag-normalise"
last_updated: "2026-06-30T06:53:07.215Z"
---

The `tag:normalise` hook is called for each individual tag during the normalization process. This hook gives you access to a single tag, its parent entry, and resolved options, allowing you to apply fine-grained modifications to specific tags.

## Lifecycle Position

This hook runs after [`entries:normalize`](/docs/head/api/hooks/entries-normalize) and before [`tags:beforeResolve`](/docs/head/api/hooks/tags-before-resolve).

## Hook Signature

```ts
export interface Hook {
  'tag:normalise': (ctx: {
    tag: HeadTag
    entry: HeadEntry<any>
    resolvedOptions: CreateClientHeadOptions
  }) => HookResult
}
```

### Parameters

<table>
<thead>
  <tr>
    <th>
      Name
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ctx
      </code>
    </td>
    
    <td>
      Object
    </td>
    
    <td>
      Context object containing the tag information
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ctx.tag
      </code>
    </td>
    
    <td>
      <code>
        HeadTag
      </code>
    </td>
    
    <td>
      The head tag being normalized
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ctx.entry
      </code>
    </td>
    
    <td>
      <code>
        HeadEntry<any>
      </code>
    </td>
    
    <td>
      The entry that generated this tag
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ctx.resolvedOptions
      </code>
    </td>
    
    <td>
      <code>
        CreateClientHeadOptions
      </code>
    </td>
    
    <td>
      The resolved options for the head instance
    </td>
  </tr>
</tbody>
</table>

### Returns

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

## Usage Example

```ts
import { createHead } from '@unhead/dynamic-import'

const head = createHead({
  hooks: {
    'tag:normalise': (ctx) => {
      const { tag, entry } = ctx

      // Apply specific modifications based on tag type
      if (tag.tag === 'link' && tag.props.rel === 'stylesheet') {
        // Add integrity check to all stylesheets
        tag.props.crossorigin = 'anonymous'
      }

      // Add source information for debugging
      tag._source = entry.options.source || 'unknown'
    }
  }
})
```

## Use Cases

### Fine-tuning Specific Tag Types

This hook is ideal for applying modifications to specific types of tags:

```ts
import { defineHeadPlugin } from '@unhead/dynamic-import'

export const scriptSecurityPlugin = defineHeadPlugin({
  hooks: {
    'tag:normalise': (ctx) => {
      const { tag } = ctx

      // Add security attributes to all script tags
      if (tag.tag === 'script' && tag.props.src) {
        // Apply Content Security Policy attributes
        tag.props.crossorigin = 'anonymous'

        // Add nonce for CSP if available
        if (globalThis.SCRIPT_NONCE) {
          tag.props.nonce = globalThis.SCRIPT_NONCE
        }
      }
    }
  }
})
```

### Tag Transformation Based on Environment

Transform tags differently based on the environment:

```ts
import { defineHeadPlugin } from '@unhead/dynamic-import'

export const environmentSpecificPlugin = defineHeadPlugin({
  hooks: {
    'tag:normalise': (ctx) => {
      const { tag, resolvedOptions } = ctx
      const isDevelopment = process.env.NODE_ENV === 'development'

      // Handle environment-specific transformations
      if (tag.tag === 'meta' && tag.props.name === 'robots') {
        // Prevent indexing in development or staging environments
        if (isDevelopment || resolvedOptions.environment === 'staging') {
          tag.props.content = 'noindex, nofollow'
        }
      }

      // Add debug information in development
      if (isDevelopment && tag.tag !== 'comment') {
        tag.props['data-dev-info'] = `Entry: ${ctx.entry._i}`
      }
    }
  }
})
```

### Custom Attribute Processing

Process custom attributes that need special handling:

```ts
import { defineHeadPlugin } from '@unhead/dynamic-import'

export const dataAttributeProcessingPlugin = defineHeadPlugin({
  hooks: {
    'tag:normalise': (ctx) => {
      const { tag } = ctx

      // Process data attributes with special formatting
      Object.keys(tag.props).forEach((prop) => {
        if (prop.startsWith('data-')) {
          // Convert camelCase values to kebab-case for data attributes
          if (typeof tag.props[prop] === 'string'
            && tag.props[prop].includes('_')) {
            tag.props[prop] = tag.props[prop]
              .replace(/_([a-z])/g, (_, char) => `-${char.toLowerCase()}`)
          }

          // Convert objects to JSON strings for data attributes
          if (typeof tag.props[prop] === 'object' && tag.props[prop] !== null) {
            tag.props[prop] = JSON.stringify(tag.props[prop])
          }
        }
      })
    }
  }
})
```