OpenWikitanstack/router

Document Head, Static Data, and Rendering

Purpose and Scope

This page explains three route-level capabilities that often appear together when polishing a TanStack Router application: document head management, static route data, and render optimization. Document head management controls the browser document metadata that affects SEO, sharing, analytics, icons, and script or style loading. Static route data attaches synchronous metadata to route definitions so layouts and other matched components can make decisions without fetching. Render optimization keeps components from re-rendering when unrelated router state changes. Together, these features help route definitions describe not only which UI appears, but also how the page integrates with the surrounding document and how efficiently it updates.

Sources: docs/router/guide/document-head-management.md, docs/router/guide/static-route-data.md, docs/router/guide/render-optimizations.md

Use this page when you are building root layouts, nested route metadata, menu visibility rules, or performance-sensitive components that subscribe to search params and router state. The important distinction is that the head option describes document tags, staticData describes synchronous route metadata attached to matches, and selector-based hooks describe what a component subscribes to at render time. These APIs do not replace loaders or route components; instead, they complement them by keeping metadata, layout policy, and subscription boundaries close to the route tree that owns the behavior.

Relevant Source Files

  • docs/router/guide/document-head-management.md - Defines the purpose of document head management, the routeOptions.head shape, <HeadContent />, <Scripts />, deduping behavior, Start/full-stack placement, SPA placement, and manifest asset crossorigin handling.
  • docs/router/guide/static-route-data.md - Documents the staticData route option, access through match.staticData, declaration merging through StaticDataRouteOption, optional versus required static data, and layout visibility patterns.
  • docs/router/guide/render-optimizations.md - Describes structural sharing, fine-grained selectors through hooks such as useRouterState and useSearch, the defaultStructuralSharing router option, per-hook structuralSharing, and the JSON-compatible data constraint.

Document Head Management

TanStack Router treats document head management as a route-owned concern. A route can define a head function that returns an object containing title, meta, links, styles, and scripts. The supplied guide emphasizes that this is useful for both TanStack Start full-stack applications and single-page applications because the document head is where pages express SEO descriptions, social sharing metadata, analytics scripts, icons, styles, and other document-level assets. In practice, this means route authors can colocate metadata with the route that owns the page, instead of maintaining a separate global registry that must be manually synchronized with navigation.

Sources: docs/router/guide/document-head-management.md

The rendering side of the contract is explicit: applications must render <HeadContent /> and <Scripts /> for the route head information and scripts to appear in the document. In Start or full-stack layouts, the guide places <HeadContent /> inside the root layout’s <head> element, with the route component returning the full HTML document shape. In single-page applications, the guide instructs developers to remove any fixed <title> from index.html and render <HeadContent /> as high in the component tree as possible when the app cannot directly manage the real <head> tag. That placement ensures active route metadata can be mounted and unmounted as matches change.

import { HeadContent } from '@tanstack/react-router'
 
export const Route = createRootRoute({
  head: () => ({
    meta: [
      { name: 'description', content: 'My App is a web application' },
      { title: 'My App' },
    ],
    links: [{ rel: 'icon', href: '/favicon.ico' }],
    scripts: [{ src: 'https://www.google-analytics.com/analytics.js' }],
  }),
  component: () => (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        <Outlet />
      </body>
    </html>
  ),
})

Nested routing affects head output through composition and deduping. The guide states that TanStack Router automatically dedupes title and meta tags and prefers the last occurrence found in nested routes. That means a child route can override a parent title, and meta tags with the same name or property are overridden by deeper matching routes. This is a useful default for layouts: a root route can provide general site metadata, section routes can add defaults, and leaf routes can supply page-specific titles or descriptions without causing duplicate meta tags for the same semantic field.

For Start-managed assets, <HeadContent /> also accepts assetCrossOrigin. The guide shows both a single string form and an object form with separate script and stylesheet values. This applies only to manifest-managed asset links emitted by Start, and it takes precedence if crossOrigin is also set via transformAssets. That detail matters in production deployments where script preloads and stylesheet links may need explicit CORS behavior. It also clarifies the boundary: route head entries define page metadata and head resources, while assetCrossOrigin tunes emitted build assets that Start injects through the head renderer.

Static Route Data

Static route data is synchronous metadata stored directly on a route’s options through staticData. The guide intentionally leaves the object open-ended: it can contain anything as long as it is available when the route is created. Because this data is attached to the route, it is also available on matches under match.staticData. That makes it a good fit for decisions that follow the route tree, such as whether a section hides a navbar, which breadcrumb label a route contributes, or what layout mode should apply to a branch. It is not a data-loading mechanism; use it for metadata known at route definition time.

Sources: docs/router/guide/static-route-data.md

A common access pattern is to define staticData in a file route and read it from a root or layout component through useMatches. The guide shows a route such as src/routes/posts.tsx setting customData: 'Hello!', then a root route mapping over matches and reading match.staticData.customData. This pattern works because matches preserve the relationship between the active URL and the route definitions that produced it. A root layout can therefore make one pass over current matches and derive document chrome, breadcrumbs, navigation visibility, or other synchronized layout decisions without coupling itself to individual route modules.

import { createFileRoute } from '@tanstack/react-router'
 
export const Route = createFileRoute('/posts')({
  staticData: {
    customData: 'Hello!',
  },
})

Static data can be made type-safe across an application by declaration merging. The guide defines StaticDataRouteOption inside the framework package module, for example @tanstack/react-router or @tanstack/solid-router. If the merged interface contains a required customData: string, routes that omit it or provide an incompatible shape receive a TypeScript error. If the property is optional, using customData?: string, routes can omit that field. The guide also notes an important nuance: as long as the interface contains any required properties, route definitions must pass a static data object that satisfies those requirements.

Static data is especially useful for layout visibility because it composes naturally with route matches. The guide’s common pattern shows an admin route setting staticData: { showNavbar: false }, and a root component deriving whether to show navigation by checking active matches. This keeps policy close to the route branch that needs it. Instead of scattering pathname checks throughout the layout, the route tree declares intent and the layout reads the current matched route metadata. That approach is easier to refactor because moving a route branch preserves the metadata attached to the route definition.

Render Optimization Patterns

Render optimization in TanStack Router centers on preserving references and limiting subscriptions. The render optimization guide defines structural sharing as preserving as many references as possible between re-renders, which is particularly valuable for URL state such as search parameters. In the guide’s example, a details route reads Route.useSearch(). When navigation changes only bar from one value to another while foo stays the same, search.foo remains referentially stable and only search.bar is replaced. That helps downstream components and memoized computations avoid work when the part of state they use has not changed.

Sources: docs/router/guide/render-optimizations.md

The second tool is fine-grained selection. Hooks such as useRouterState, useSearch, and route-specific search hooks accept a select option so components can subscribe to only the subset of router state they need. The guide’s simple example selects only foo from search params, so the component does not re-render when bar changes. This is the preferred mental model for performance-sensitive UI: avoid subscribing to whole router objects when a component only needs one field. The selector makes the dependency explicit, and the router can compare the selected value rather than treating every state change as relevant.

const foo = Route.useSearch({
  select: ({ foo }) => foo,
})

Selectors can return derived objects, but that introduces a subtle performance issue. If a selector returns a new object each time, the selected value has a new reference even when its fields are logically unchanged. The guide addresses this with structural sharing for fine-grained selectors. Structural sharing is off by default for backward compatibility, but it can be enabled globally with defaultStructuralSharing: true when creating the router, or per hook call with structuralSharing: true. The per-hook option is useful when only specific derived selectors need reference preservation, while the router option establishes a broader application default.

const router = createRouter({
  routeTree,
  defaultStructuralSharing: true,
})
 
const result = Route.useSearch({
  select: (search) => ({
    foo: search.foo,
    hello: `hello ${search.foo}`,
  }),
  structuralSharing: true,
})

The guide calls out an important constraint: structural sharing only works with JSON-compatible data. If a selector returns class instances or values like new Date() while structural sharing is enabled, TypeScript raises an error. If structural sharing is enabled by default and a selector truly needs to return a non-JSON-compatible value, the guide shows that the hook can opt out with structuralSharing: false. This constraint is not just an implementation detail; it keeps referential comparison predictable for URL-derived state and prevents object identity from hiding non-serializable values inside router subscriptions.

System-to-Code Mapping

At the route-definition level, head and staticData solve different metadata problems. Use head when the output must become document tags: titles, descriptions, icons, links, inline styles, or scripts. Use staticData when the output should remain application metadata attached to route matches: layout flags, breadcrumb labels, navigation grouping, or other synchronous policy. Both are declared on routes, but their consumers differ. <HeadContent /> materializes head data into the document, while hooks such as useMatches expose static data to components that render layout and navigation decisions.

Sources: docs/router/guide/document-head-management.md, docs/router/guide/static-route-data.md

Render optimization then governs how components consume the resulting router state. A root layout that reads all matches to compute a navbar should consider selecting only the fields it needs when using hooks that support selectors. A page component that reads search state should prefer selecting the exact search parameter or derived object it needs, and enable structural sharing when returning object-shaped derived data. This keeps metadata-rich route trees scalable: routes can declare document and layout information, while components subscribe narrowly enough that unrelated URL or match changes do not cause unnecessary rendering.

Sources: docs/router/guide/render-optimizations.md

Implementation Checklist

When implementing these features, start at the root route. Add <HeadContent /> in the document <head> for Start or full-document rendering, or near the top of the app tree for an SPA after removing a fixed index.html title. Add <Scripts /> where your application renders script output. Then add route-level head functions beginning with root defaults and overriding them in nested routes where page-specific metadata is needed. Review duplicate titles and meta names with the deduping rule in mind: deeper matching routes win for title and same-key meta tags.

Next, decide whether your application has route metadata that should be typed. If every route or a class of routes must provide specific static metadata, merge StaticDataRouteOption into the framework module and make fields required. If the metadata is only sometimes present, make the fields optional and handle absence in match consumers. For layout behavior, prefer route-owned staticData over path string checks. Finally, inspect components that read search params or router state. Add select callbacks for narrow subscriptions, enable structural sharing for object-shaped derived values, and avoid non-JSON-compatible selector results unless you explicitly disable structural sharing for that hook.

Read search-params next if your render optimization work involves URL state shape, validation, or defaults. Read route-trees-layouts-outlets for the layout composition model that makes staticData useful across nested matches. Read server-side-rendering and start-rendering-and-hydration when document head output is part of a Start or SSR application rather than a client-only app. For API-level names and signatures, continue to routes-api-reference, router-hooks-api-reference, and router-options-state-events.

Ask a question...