Unhead
TypeScript

Template Params Plugin

On this page

Introduction

The Template Params plugin lets you define variables that can be used across your meta tags. While you could use functions for dynamic content, template params work better with SSR and avoid hydration issues.

Setup

Add the plugin to your Unhead configuration:

Input
import { createHead } from 'unhead'
import { TemplateParamsPlugin } from 'unhead/plugins'

const head = createHead({
  plugins: [
    TemplateParamsPlugin()
  ]
})

Built-in Params

Unhead includes two built-in template params:

TokenDescription
%sThe current page title
%separatorSmart separator (defaults to |)

The %separator is intelligent - it only appears between content and removes itself when:

  • The title is empty
  • Multiple separators would appear next to each other
Input
useHead(unheadInstance, {
  title: 'Home',
  titleTemplate: '%s %separator %siteName',
  templateParams: {
    separator: '—', // Use an em dash instead of |
    siteName: 'MySite'
  }
})
Output
<title>Home — MySite</title>

Separator Options

For better readability, consider these separator alternatives:

Input
// Choose a more readable separator
useHead(unheadInstance, {
  templateParams: {
    separator: '—' // Em dash
    // Other options: '-' (hyphen), '•' (bullet), '·' (middot), '❤️' (heart)
  }
})

Meta Tags and Social Sharing

Template params work seamlessly with SEO meta tags and social sharing:

Input
useHead(unheadInstance, {
  templateParams: {
    siteName: 'MyApp',
    separator: '·'
  },
  title: 'Home',
  meta: [
    { name: 'description', content: 'Welcome to %siteName - where we make awesome happen' },
    { property: 'og:title', content: 'Home %separator %siteName' },
    { property: 'og:description', content: 'Check out %siteName today!' }
  ]
})
Output
<head>
  <title>Home · MyApp</title>
  <meta name="description" content="Welcome to MyApp - where we make awesome happen">
  <meta property="og:title" content="Home · MyApp">
  <meta property="og:description" content="Check out MyApp today!">
</head>

Using with Other Tags

Enable for Script and Other Tags

For tags using innerHTML or textContent, add processTemplateParams: true:

Input
useHead(unheadInstance, {
  templateParams: { name: 'My App' },
  script: [
    {
      innerHTML: { name: '%name' },
      type: 'application/json',
      processTemplateParams: true
    }
  ]
})
Output
<script type="application/json">{ "name": "My App" }</script>

Disable for Specific Tags

Add processTemplateParams: false to skip template processing:

Input
useHead(unheadInstance, {
  title: 'Hello %name',
  templateParams: { name: 'World' },
}, {
  processTemplateParams: false,
})
Output
<title>Hello %name</title>

Common Use Cases

Brand Consistency

Maintain consistent branding across your site:

Input
// In your site setup
const head = createHead({
  plugins: [
    TemplateParamsPlugin()
  ]
})

// Define global template params
head.push({
  templateParams: {
    brand: 'ProductName™',
    tagline: 'The best solution for your needs',
    separator: '—'
  }
})

// In page components
useHead(unheadInstance, {
  title: 'Features',
  titleTemplate: '%s %separator %brand',
  meta: [
    { name: 'description', content: '%brand: %tagline' }
  ]
})

Nested Objects

Use nested objects for more structured data:

Input
useHead(unheadInstance, {
  templateParams: {
    site: {
      name: 'My Site',
      url: 'https://example.com',
    },
    separator: '·',
    subPage: null
  },
  title: 'My Page',
  titleTemplate: '%s %separator %subPage %separator %site.name',
  meta: [
    {
      name: 'description',
      content: 'Welcome to %site.name.',
    },
    {
      property: 'og:site_name',
      content: '%site.name',
    },
    {
      property: 'og:url',
      content: '%site.url/my-page',
    },
  ],
})
Output
<head>
<title>My Page · My Site</title>
<meta name="description" content="Welcome to My Site.">
<meta property="og:site_name" content="My Site">
<meta property="og:url" content="https://example.com/my-page">
</head>
Edit this page
Markdown For LLMs
Did this page help you?