Core Concepts

Page Titles with Unhead

On this page

Introduction
Understanding the Title Tags
Core Concepts
Dynamic Page Titles with useHead()
Setting Up Title Templates
Common Use Cases
Best Practices

Introduction

Page titles are crucial for SEO. They're your primary call-to-action in search results and help users understand your page's content and context.

<head>
  <title>Mastering Titles · My App</title>
</head>

Page titles are often the first impression users have of your site in search results. Well-crafted titles can significantly improve click-through rates.

While setting page titles with Unhead is straightforward, certain scenarios can be tricky. Let's start with the essential patterns you should follow.

Understanding the Title Tags

The <title> tag displays text in browser tabs and typically appears as your page's heading in search engine results (SERPs).

When working with JavaScript frameworks, you might be tempted to set titles directly:

// ❌ Careful! This won't work in SSR
document.title = 'Home'

This approach has two major issues:

It breaks during Server-Side Rendering (SSR)
Search engines may not properly index your titles

New to SEO titles? Check out Google's guide on Influencing your title links in search results.

Core Concepts

Unhead provides a simple yet powerful API for managing page titles across different rendering contexts (SSR and CSR) that works with any JavaScript framework.

Dynamic Page Titles with `useHead()`

Now that we understand why direct title manipulation won't work, let's use Unhead's useHead() composable to set titles properly:

import { useHead } from '@unhead/react'

useHead({
  title: 'Home'
})

<head>
  <title>Home</title>
</head>

This single line creates an SSR-friendly title that search engines can read. The composable handles all the complexity of managing your document head in both client and server environments.

You can use this in any component and set any <head> tag you like.

import { useHead } from '@unhead/react'

useHead({
  title: 'Home',
  meta: [
    { name: 'description', content: 'Welcome to MyApp' }
  ]
})

Unhead will automatically dedupe title tags if you set them in multiple components. The last one to render will take precedence.

The useHead() API works the same way across all supported frameworks (Vue, React, Svelte, Solid, and Angular). The only difference is how reactivity is handled in each framework.

Setting Up Title Templates

You may notice that most people set up their titles with a site name and a separator, this is seen as a best practice as it can help with brand recognition and SEO.

<head>
  <title>Home | MySite</title>
</head>

Creating your own title like this is simple using useHead() with a title template.

import { useHead } from '@unhead/react'

useHead({
  title: 'Home',
  titleTemplate: '%s | MySite'
})

<head>
  <title>Home | MySite</title>
</head>

Template params like %s act as placeholders that get replaced with your page title and separator.

Template Params

Template params are an opt-in plugin make your tags more dynamic. You get %s and %separator built-in, and can add your own:

Input

import { useHead } from '@unhead/react'

useHead({
  title: 'Home',
  titleTemplate: '%s %separator %siteName',
  templateParams: {
    separator: '·',
    siteName: 'My Site'
  }
})

Output

<title>Home · My Site</title>

Template params work with all head tags, not just titles. This makes them powerful for reusing branded elements across your site.

Check out the Template Params guide to get started.

Resetting the Title Template

If you need to reset the title template for a specific page, you can pass null to the titleTemplate option.

<script lang="ts" setup>
import { useHead } from '@unhead/react'

useHead({
  title: 'Home',
  titleTemplate: null
})
</script>

<head>
  <title>Home</title>
</head>

Resetting the title template will remove any branding elements from your page title. Only do this for specific pages like the homepage where the full branding isn't needed.

Social platforms use different meta tags for sharing titles.

In the above we can see the title "Nuxt: The Intuitive Vue Framework".

This title is set using the twitter:title meta tag and will fall back to the og:title meta tag if not set.

Remembering how to use the meta tags can be annoying, so we can use the useSeoMeta() composable to set these up.

import { useSeoMeta } from '@unhead/react'

useSeoMeta({
  titleTemplate: '%s | Health Tips',
  title: 'Why you should eat more broccoli',
  // og title is not effected by titleTemplate, we can use template params here if we need
  ogTitle: 'Hey! Health Tips - 10 reasons to eat more broccoli.',
  // explicit twitter title is only needed when we want to display something just for X
  twitterTitle: 'Hey X! Health Tips - 10 reasons to eat more broccoli.',
})

<head>
  <title>Why you should eat more broccoli | Health Tips</title>
  <meta property="og:title" content="Health Tips: 10 reasons to eat more broccoli." />
  <meta name="twitter:title" content="Hey X! Health Tips - 10 reasons to eat more broccoli." />
</head>

The useSeoMeta API is identical across all supported frameworks - Vue, React, Svelte, Solid, and Angular.

Common Use Cases

Here are some practical examples for handling page titles in different scenarios.

Reactive Titles

Titles can be reactive, updating when your component data changes. Here's how this works in different frameworks:

import { useHead } from '@unhead/react'
import { ref } from 'vue'

const productName = ref('Widget X')
const isLoading = ref(true)

useHead({
  title: () => isLoading.value
    ? 'Loading...'
    : `Product: ${productName.value}`
})

import { useHead } from '@unhead/react'
import { useState } from 'react'

function ProductPage() {
  const [productName, setProductName] = useState('Widget X')
  const [isLoading, setIsLoading] = useState(true)

  useHead({
    title: () => isLoading
      ? 'Loading...'
      : `Product: ${productName}`
  })

  return <div>Product Page</div>
}

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

function ProductPage() {
  const [productName, setProductName] = createSignal('Widget X')
  const [isLoading, setIsLoading] = createSignal(true)

  useHead({
    title: () => isLoading()
      ? 'Loading...'
      : `Product: ${productName()}`
  })

  return <div>Product Page</div>
}

Hierarchical Titles

For nested pages like documentation, show hierarchy:

import { useHead } from '@unhead/react'

// Works in any framework
useHead({
  title: 'Installation',
  titleTemplate: '%s | Documentation | MyApp'
})

Language-Specific Titles

For multilingual sites:

import { useHead } from '@unhead/react'

// In a real app, you'd get this from your i18n library
const locale = 'en'

const titles = {
  en: 'Welcome',
  fr: 'Bienvenue',
  es: 'Bienvenido'
}

useHead({
  title: titles[locale] || titles.en,
  htmlAttrs: {
    lang: locale
  }
})

import { useHead } from '@unhead/react'
import { useTranslation } from 'react-i18n' // Example i18n library

function HomePage() {
  const { t, i18n } = useTranslation()

  useHead({
    title: t('home.title'),
    htmlAttrs: {
      lang: i18n.language
    }
  })

  return <div>Home Page</div>
}