Quick Start

This page shows the shortest path to integrate TanStack Head Controller into a TanStack Router app.

1. Install packages

ninpmpnpm

ni tanstack-head-controller thc-plugin-merge thc-plugin-ttplate

npm install tanstack-head-controller thc-plugin-merge thc-plugin-ttplate

pnpm add tanstack-head-controller thc-plugin-merge thc-plugin-ttplate

2. Create a controller and place it in router context

router.tsx

tsx

import { createRouter } from '@tanstack/react-router'
import { createHeadController } from 'tanstack-head-controller'
import { thcMerge } from 'thc-plugin-merge'
import { thcTitleTemplate } from 'thc-plugin-ttplate'

export const router = createRouter({
  routeTree,
  context: {
    ...createHeadController({
      plugins: [
        thcMerge(),
        thcTitleTemplate({
          siteName: "My App"
        })
      ]
    })
  },
})

3. Render in your root document head

__root.tsx

tsx

import { HeadControllerRender } from 'tanstack-head-controller'

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html lang='en'>
      <head>
        <HeadControllerRender />
      </head>
      <body>{children}</body>
    </html>
  )
}

4. Define head at route level

about.tsx

tsx

export const Route = createFileRoute('/about')({
  head: () => ({
    meta: [
      { title: 'About' },
      { property: 'og:title', content: 'About' },
    ],
  }),
})

5. Optionally edit route context

This example uses editContext, but the key idea is simple: keep existing route context intact and add only the settings you need.

about.tsx

tsx

import { editContext } from 'tanstack-head-controller/context'

export const Route = createFileRoute('/about')({
  context: (ctx) =>
    editContext(ctx, {
      configs: { debug: true },
    }),
})

Next, see Usage for plugin patterns and practical tips.

Quick Start ​

1. Install packages ​

2. Create a controller and place it in router context ​

3. Render in your root document head ​

4. Define head at route level ​

5. Optionally edit route context ​