Reactive head(): update title/meta when async data arrives after non-blocking navigation

[meseven]

Problem

In a SPA using the recommended TanStack Query integration, loaders typically call queryClient.ensureQueryData() without awaiting so navigation stays instant, and components read the data with useSuspenseQuery. In this setup head({ loaderData }) can't produce a dynamic title: loaderData is empty when head() runs, and head() is never re-invoked once the data lands in the cache.

Current options all have drawbacks:

• Await the loader → blocks navigation, defeating the non-blocking pattern.
• useEffect + document.title after Suspense resolves → works, but bypasses HeadContent, and only by relying on the (undocumented) fact that HeadContent won't rewrite an unchanged title.
• React 19 <title> hoisting → conflicts with the <title> that HeadContent renders (duplicate tags, first-in-document wins).

Proposal

First-class support for a two-phase title: a static fallback shown at navigation, replaced when async data resolves. Possible shapes:

1. Re-run head() when an unawaited/deferred promise returned from the loader resolves (Await-aware head), or
2. A supported API for a route component to update its own match's head after data arrives — e.g. a useHead() hook or <RouteHead title={...} /> component that participates in HeadContent's dedupe/override chain.

Related

• How to set html tag title from a route #1056 — long-running thread; every SPA answer there ends in a document.title workaround
• Route head function can still execute before loader function finishes #6221 — head running before the loader finishes (the awaited case)

[MILLERMARRU]

There's a documented pattern for exactly this in the router-context guide, and it sidesteps the three approaches you listed because it doesn't try to make head() itself reactive, it reads reactive state from inside a normal component render instead:

export const Route = createRootRoute({
  component: () => {
    const matches = useRouterState({ select: (s) => s.matches })
    const matchWithTitle = [...matches].reverse().find((d) => d.context.getTitle)
    const title = matchWithTitle?.context.getTitle() || 'My App'

    return (
      <html>
        <head><title>{title}</title></head>
        <body>{/* ... */}</body>
      </html>
    )
  },
})

The key difference from head(): this runs as part of the root route's normal React render, not as a separate static/serializable descriptor evaluated at match time. Since it's a real component, it re-renders whenever whatever it reads changes, including a useSuspenseQuery resolving after your non-blocking ensureQueryData() call. You'd swap context.getTitle() for reading your query's data directly (or through the same match-context pattern, populating context.getTitle from the loader once data starts flowing).

This is also why it avoids your two failure modes: it goes through the router's own <title> element (so HeadContent's dedupe logic is aware of it, unlike a raw document.title mutation from useEffect), and it isn't React 19's native <title> hoisting competing with a second one from HeadContent, since there's only one <title> in the tree, the reactive one, rendered directly in the root component rather than assembled from static head() results across matches.

[meseven]

Thanks — that's the pattern from the router-context guide, and it works well when loaders are awaited: the loader finishing updates router state, the root re-renders, and getTitle() returns fresh data.

The gap is in the non-blocking case this discussion is about: with ensureQueryData() fired and not awaited, the data lands in the QueryClient cache without any router state change. useRouterState never fires, and context.getTitle() is a plain closure, not a subscription — so nothing re-renders the root, and the title sits on the fallback until some unrelated render happens. The missing piece is a subscription to the data source, not just reading it during render.

To check whether userland can close that gap, we prototyped the subscription variant in our app: routes put { queryKey, queryFn, select, fallback } into context from beforeLoad, and a small component next to <HeadContent /> in the root subscribes with useQuery and renders a single <title>. It does work — the tab title updates the moment the data arrives, with no router.invalidate() involved. But getting it correct required rebuilding a surprising amount of head machinery:

• HeadContent renders a <title> whenever any match's head() returns one, so keeping exactly one <title> in the tree meant dropping the root's default title and adding precedence rules between static head() titles and dynamic context titles (deepest wins).
• Route context is inherited by reference, so the context entry also appears on child matches. We had to track the depth where it was declared — otherwise a child route's static head() title lost to its parent's inherited dynamic one, and we shipped a duplicate <title> before catching it.
• The query fn/selector generics have to be erased at the context boundary, since route context has a single static type.

All of that re-implements what head() already expresses declaratively; the only thing missing from head() itself is reactivity. Which is why first-class support — re-running head() when a deferred value resolves, or a head primitive that can subscribe — still seems worth it: every userland version ends up rebuilding head merging and precedence by hand.

[Axxxx0n]

Worth adding that this isn't SPA-only — it bites SSR apps too.

If a route awaits its loader on the server but skips it on the client to keep
navigation instant:

loader: ({ context, params }) => {
  if(typeof document === undefined) {
    const q = await context.queryClient.query(postQuery(params.postId))
    return q
  }
  
  return  undefined
},
head: ({ loaderData }) =>
  loaderData ? { meta: [{ title: loaderData.title }] } : {},

then head() only ever produces real tags on the initial document request.
Every client-side navigation after that gets loaderData === undefined and falls
back to the root's tags, and head() is never re-invoked once the query resolves.

So you get correct metadata for crawlers and a hard refresh, and stale metadata for
the entire rest of the session. There is no way to set it in component render after query resolves.

[juliomuhlbauer]

+1 on this, and a gentle bump for maintainer input. 🙏

Our use case (TanStack Start, SSR streaming): on listing/region pages the title, description, OG image and canonical depend on loader data, so today we have to await that data before the shell can stream. Anything that also feeds the <head> or JSON-LD (e.g. breadcrumb regions) ends up blocking TTFB too.

It would help to know the intended direction:

1. Is a reactive head() (re-run when deferred data resolves) or a useHead() hook on the roadmap?
2. For SSR, is the official recommendation still "await everything head() needs, defer the rest" (as in How to set html tag title from a route #1056)?

Even a short answer would help us (and others) decide whether to wait for an API or design around it.