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

meseven · 2026-07-23T15:10:25Z

meseven
Jul 23, 2026

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:

Re-run head() when an unawaited/deferred promise returned from the loader resolves (Await-aware head), or
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.

MILLERMARRU
Aug 8, 2026

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.

1 reply

meseven Aug 10, 2026
Author

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.

Navigation Menu

Uh oh!

Uh oh!

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

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment 1 reply

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

meseven Jul 23, 2026

Problem

Proposal

Related

Replies: 1 comment · 1 reply

Uh oh!

MILLERMARRU Aug 8, 2026

Uh oh!

meseven Aug 10, 2026 Author

meseven
Jul 23, 2026

Replies: 1 comment 1 reply

MILLERMARRU
Aug 8, 2026

meseven Aug 10, 2026
Author