Tag Deduplication

Quick Answer: Unhead automatically deduplicates tags by key attribute. Meta tags dedupe by name or property. Use unique key values when you need multiple similar tags.

What Is Tag Deduplication?

When implementing head tags across an application hierarchy (layouts, pages, components), you'll often need to override tags. This automatic replacement of duplicate tags is called "deduplication" or "deduping."

Unhead intelligently determines which tags are duplicates based on HTML specifications about which elements can appear multiple times in the DOM.

For example, you can only have one title element, and a single <meta name="description"> tag in a valid HTML document.

How Does Deduplication Work?

When you register multiple tags that are considered duplicates, only the most recent one will be used by default. This allows page-level components to override tags defined at the layout level.

How Are Duplicates Identified?

Unhead uses several strategies to identify duplicate tags:

• Special singleton tags: base, title, titleTemplate, bodyAttrs, htmlAttrs
• Specific link types: <link rel="canonical">
• Charset metadata: <meta charset="">
• Custom keys: Any tag with a matching key attribute
• Meta tag identifiers: Matching name, property, or http-equiv attributes

Example: Meta Description Override

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

// useHead: /docs/head/api/composables/use-head
// Called in a layout component (higher in the hierarchy)
useHead({
  meta: [
    {
      name: 'description',
      content: 'my site wide description',
    },
  ],
})

// Called in a page component (lower in the hierarchy)
useHead({
  meta: [
    {
      name: 'description',
      content: 'my page description',
    },
  ],
})

// Result in the rendered HTML:
// <meta name="description" content="my page description" />

How Do I Allow Multiple Tags with the Same Name?

While deduplication is useful in most cases, there are scenarios where you need multiple tags with the same identifiers. A common example is verification tags from multiple services.

Using Content Arrays

To have multiple meta tags with the same name attribute, you can provide an array of values for the content attribute:

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

useHead({
  meta: [
    {
      name: 'google-site-verification',
      content: [
        'verification-id-1',
        'verification-id-2',
      ]
    },
  ],
})

// Result in HTML:
// <meta name="google-site-verification" content="verification-id-1">
// <meta name="google-site-verification" content="verification-id-2">

Multiple Tags in a Single Entry

Unhead also intelligently preserves multiple tags with the same identifier when they're defined within a single useHead() call:

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

useHead({
  meta: [
    {
      name: 'google-site-verification',
      content: 'verification-id-1'
    },
    {
      name: 'google-site-verification',
      content: 'verification-id-2'
    },
  ],
})

// Result in HTML:
// <meta name="google-site-verification" content="verification-id-1">
// <meta name="google-site-verification" content="verification-id-2">

How Do I Use Custom Keys for Deduplication?

When you need more fine-grained control over deduplication, you can provide a custom key attribute to your tags.

The key serves as a unique identifier, ensuring that only one instance of a tag with that key exists in the final HTML output. This works regardless of the tag type or other attributes.

Example: Ensuring Script Uniqueness

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

useHead({
  script: [
    {
      src: 'https://example.com/script.js',
      key: 'my-script',
    },
  ]
})

Overriding Tags Using Keys

Any tag can be overridden or removed by using the same key in a subsequent useHead() call, regardless of the tag type or other properties.

How Do I Customize the Duplicate Handling Strategy?

By default, when a duplicate tag is found, Unhead will replace the existing tag with the new one.

Default Strategies

• For most tags: The default strategy is replace - the new tag completely replaces the old one
• For attribute tags: When dealing with htmlAttrs and bodyAttrs, the default strategy is merge - allowing you to add attributes without removing existing ones (especially useful for class and style properties)

The tagDuplicateStrategy Property

You can explicitly control this behavior using the tagDuplicateStrategy property:

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

// In a layout file we added a class
useHead({
  htmlAttrs: {
    class: 'my-class',
  },
})

// On a specific page, we want to replace instead of merge
useHead({
  htmlAttrs: {
    tagDuplicateStrategy: 'replace', // Override the default merge behavior
    class: 'my-new-class',
  },
})

// Result in HTML:
// <html class="my-new-class">

Practical Examples

How Do I Remove a Tag from a Parent Component?

You can remove a tag defined in a parent component by using its key with an empty object:

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

// A layout file sets the background color to red
useHead({
  style: [
    {
      key: 'red-bg',
      textContent: 'body { color: red }',
    }
  ]
})

// On a specific page, we want to remove that style
useHead({
  style: [
    {
      // A tag with only a key will be removed
      key: 'red-bg',
    }
  ]
})

// Result: No style is rendered

How Do I Replace a Style with a Different Value?

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

// A layout file sets the background color to red
useHead({
  style: [
    {
      key: 'bg-colour',
      textContent: 'body { color: red }',
    }
  ]
})

// In a page component, we want to change it to blue
useHead({
  style: [
    {
      key: 'bg-colour',
      textContent: 'body { color: blue }',
    }
  ]
})

// Result: Only the blue style is rendered

Common Use Cases

• Layout/Page Overrides: Define base tags in layouts and override them in specific pages
• Component-Specific Tags: Add tags in components that won't conflict with others
• Feature Toggles: Enable/disable certain tags based on feature flags
• Third-Party Integrations: Manage verification tags from multiple services
• Environment-Specific Settings: Change tags based on development, staging, or production environments

Key Takeaways

See Also

• Tag Positions - Control tag ordering
• useHead() API - Deduplication options