TanStack · schiller-manuel · Jun 27, 2025 · Jun 26, 2025
diff --git a/examples/react/navigation-blocking/src/main.tsx b/examples/react/navigation-blocking/src/main.tsx
@@ -130,7 +130,7 @@ const fooRoute = createRoute({
   getParentRoute: () => rootRoute,
   path: 'foo/$id',
   validateSearch: (search) => ({ hello: search.hello }) as { hello: string },
-  component: () => <>foo {fooRoute.useParams().id}</>,
+  component: () => <div>foo {fooRoute.useParams().id}</div>,
 })
 
 const editor1Route = createRoute({

diff --git a/examples/react/start-basic/src/routes/__root.tsx b/examples/react/start-basic/src/routes/__root.tsx
@@ -2,7 +2,6 @@
 import {
   HeadContent,
   Link,
-  Outlet,
   Scripts,
   createRootRoute,
 } from '@tanstack/react-router'
@@ -58,25 +57,11 @@ export const Route = createRootRoute({
       },
     ],
   }),
-  errorComponent: (props) => {
-    return (
-      <RootDocument>
-        <DefaultCatchBoundary {...props} />
-      </RootDocument>
-    )
-  },
+  errorComponent: DefaultCatchBoundary,
   notFoundComponent: () => <NotFound />,
-  component: RootComponent,
+  shellComponent: RootDocument,
 })
 
-function RootComponent() {
-  return (
-    <RootDocument>
-      <Outlet />
-    </RootDocument>
-  )
-}
-
 function RootDocument({ children }: { children: React.ReactNode }) {
   return (
     <html>

diff --git a/examples/solid/start-basic/src/routes/__root.tsx b/examples/solid/start-basic/src/routes/__root.tsx
@@ -2,7 +2,6 @@
 import {
   HeadContent,
   Link,
-  Outlet,
   Scripts,
   createRootRoute,
 } from '@tanstack/solid-router'
@@ -52,25 +51,11 @@ export const Route = createRootRoute({
       { rel: 'icon', href: '/favicon.ico' },
     ],
   }),
-  errorComponent: (props) => {
-    return (
-      <RootDocument>
-        <DefaultCatchBoundary {...props} />
-      </RootDocument>
-    )
-  },
+  errorComponent: DefaultCatchBoundary,
   notFoundComponent: () => <NotFound />,
-  component: RootComponent,
+  shellComponent: RootDocument,
 })
 
-function RootComponent() {
-  return (
-    <RootDocument>
-      <Outlet />
-    </RootDocument>
-  )
-}
-
 function RootDocument({ children }: { children: Solid.JSX.Element }) {
   return (
     <>

diff --git a/packages/react-router/src/Match.tsx b/packages/react-router/src/Match.tsx
@@ -17,7 +17,11 @@ import { matchContext } from './matchContext'
 import { SafeFragment } from './SafeFragment'
 import { renderRouteNotFound } from './renderRouteNotFound'
 import { ScrollRestoration } from './scroll-restoration'
-import type { AnyRoute, ParsedLocation } from '@tanstack/router-core'
+import type {
+  AnyRoute,
+  ParsedLocation,
+  RootRouteOptions,
+} from '@tanstack/router-core'
 
 export const Match = React.memo(function MatchImpl({
   matchId,
@@ -80,8 +84,11 @@ export const Match = React.memo(function MatchImpl({
     },
   })
 
+  const ShellComponent = route.isRoot
+    ? ((route.options as RootRouteOptions).shellComponent ?? SafeFragment)
+    : SafeFragment
   return (
-    <>
+    <ShellComponent>
       <matchContext.Provider value={matchId}>
         <ResolvedSuspenseBoundary fallback={pendingElement}>
           <ResolvedCatchBoundary
@@ -119,7 +126,7 @@ export const Match = React.memo(function MatchImpl({
           <ScrollRestoration />
         </>
       ) : null}
-    </>
+    </ShellComponent>
   )
 })
 

diff --git a/packages/react-router/src/Matches.tsx b/packages/react-router/src/Matches.tsx
@@ -11,7 +11,6 @@ import type {
   StructuralSharingOption,
   ValidateSelected,
 } from './structuralSharing'
-import type { ReactNode } from './route'
 import type {
   AnyRouter,
   DeepPartial,
@@ -154,7 +153,7 @@ export type MakeMatchRouteOptions<
           TRouter['routeTree'],
           ResolveRelativePath<TFrom, NoInfer<TTo>>
         >['types']['allParams'],
-      ) => ReactNode)
+      ) => React.ReactNode)
     | React.ReactNode
 }
 

diff --git a/packages/react-router/src/index.tsx b/packages/react-router/src/index.tsx
@@ -284,7 +284,6 @@ export {
 } from './route'
 export type {
   AnyRootRoute,
-  ReactNode,
   SyncRouteComponent,
   AsyncRouteComponent,
   RouteComponent,

diff --git a/packages/react-router/src/route.tsx b/packages/react-router/src/route.tsx
@@ -54,6 +54,14 @@ declare module '@tanstack/router-core' {
     pendingComponent?: RouteComponent
   }
 
+  export interface RootRouteOptionsExtensions {
+    shellComponent?: ({
+      children,
+    }: {
+      children: React.ReactNode
+    }) => React.ReactNode
+  }
+
   export interface RouteExtensions<
     in out TId extends string,
     in out TFullPath extends string,
@@ -534,11 +542,9 @@ export function createRouteMask<
   return opts as any
 }
 
-export type ReactNode = any
-
 export type SyncRouteComponent<TProps> =
-  | ((props: TProps) => ReactNode)
-  | React.LazyExoticComponent<(props: TProps) => ReactNode>
+  | React.FC<TProps>
+  | React.LazyExoticComponent<(props: TProps) => React.ReactNode>
 
 export type AsyncRouteComponent<TProps> = SyncRouteComponent<TProps> & {
   preload?: () => Promise<void>

diff --git a/packages/react-router/tests/router.test.tsx b/packages/react-router/tests/router.test.tsx
@@ -1458,6 +1458,7 @@ describe('search params in URL', () => {
           validateSearch,
           errorComponent: ({ error }) => {
             errorSpy = error
+            return null
           },
         })
 
@@ -1477,6 +1478,7 @@ describe('search params in URL', () => {
           validateSearch,
           errorComponent: ({ error }) => {
             errorSpy = error
+            return null
           },
         })
 

diff --git a/packages/router-core/src/index.ts b/packages/router-core/src/index.ts
@@ -187,6 +187,7 @@ export type {
   RouteContextOptions,
   BeforeLoadContextOptions,
   RootRouteOptions,
+  RootRouteOptionsExtensions,
   UpdatableRouteOptionsExtensions,
   RouteConstraints,
   RouteTypesById,

diff --git a/packages/router-core/src/route.ts b/packages/router-core/src/route.ts
@@ -1205,6 +1205,13 @@ export interface LoaderFnContext<
   route: AnyRoute
 }
 
+export interface DefaultRootRouteOptionsExtensions {
+  shellComponent?: unknown
+}
+
+export interface RootRouteOptionsExtensions
+  extends DefaultRootRouteOptionsExtensions {}
+
 export type RootRouteOptions<
   TSearchValidator = undefined,
   TRouterContext = {},
@@ -1234,7 +1241,8 @@ export type RootRouteOptions<
   | 'parseParams'
   | 'stringifyParams'
   | 'params'
->
+> &
+  RootRouteOptionsExtensions
 
 export type RouteConstraints = {
   TParentRoute: AnyRoute

diff --git a/packages/solid-router/src/Match.tsx b/packages/solid-router/src/Match.tsx
@@ -18,7 +18,7 @@ import { matchContext } from './matchContext'
 import { SafeFragment } from './SafeFragment'
 import { renderRouteNotFound } from './renderRouteNotFound'
 import { ScrollRestoration } from './scroll-restoration'
-import type { AnyRoute } from '@tanstack/router-core'
+import type { AnyRoute, RootRouteOptions } from '@tanstack/router-core'
 
 export const Match = (props: { matchId: string }) => {
   const router = useRouter()
@@ -77,8 +77,12 @@ export const Match = (props: { matchId: string }) => {
     },
   })
 
+  const ShellComponent = route().isRoot
+    ? ((route().options as RootRouteOptions).shellComponent ?? SafeFragment)
+    : SafeFragment
+
   return (
-    <>
+    <ShellComponent>
       <matchContext.Provider value={() => props.matchId}>
         <Dynamic
           component={ResolvedSuspenseBoundary()}
@@ -124,7 +128,7 @@ export const Match = (props: { matchId: string }) => {
           <ScrollRestoration />
         </>
       ) : null}
-    </>
+    </ShellComponent>
   )
 }
 

diff --git a/packages/solid-router/src/route.tsx b/packages/solid-router/src/route.tsx
@@ -54,6 +54,14 @@ declare module '@tanstack/router-core' {
     pendingComponent?: RouteComponent
   }
 
+  export interface RootRouteOptionsExtensions {
+    shellComponent?: ({
+      children,
+    }: {
+      children: Solid.JSX.Element
+    }) => Solid.JSX.Element
+  }
+
   export interface RouteExtensions<
     in out TId extends string,
     in out TFullPath extends string,