Nested Routes & Context — React Deep Dive

a match is a chain, not a single component

When TanStack Router matches /admin/users/42, it does not render one component. It resolves the leaf (UserDetail) and walks its ancestor chain: [Root, Admin, Users, UserDetail]. Each ancestor renders as a layout with an <Outlet/> placeholder, and the next route in the chain renders inside it — nested rendering. At the same time, each route's beforeLoad returns a context object that is merged down the chain, so the leaf receives the union of every ancestor's context.

route	beforeLoad provides	component renders	inherited at this level
`/` Root	`{'{ theme, user }'}`	header + `<Outlet/>`	`{'{ theme, user }'}`
`/admin`	`{'{ adminMode }'}`	sidebar + `<Outlet/>`	`{'{ theme, user, adminMode }'}`
`/admin/users`	`{'{ userFilter }'}`	UserList	`{'{ theme, user, adminMode, userFilter }'}`
`/admin/users/$id`	`{'{ detailTab }'}`	UserDetail	`{'{ theme, user, adminMode, userFilter, detailTab }'}`

The chain only includes ancestors of the matched leaf. Navigate to /admin and the chain collapses to [Root, Admin] — Users and UserDetail never mount, so userFilter/detailTab are absent from context.

1 · the nested-context visualizer (edit me)

// ── Route hierarchy: each node provides context + renders a layout/leaf ──
//   parent links form the ancestor chain; contextProvided merges top-down.
var routeHierarchy = [
  { path: '/', name: 'Root', parent: null,
    contextProvided: { theme: 'dark', user: 'admin' },
    renders: 'Layout (header + Outlet)' },
  { path: '/admin', name: 'Admin', parent: 'Root',
    contextProvided: { adminMode: true },
    renders: 'AdminLayout (sidebar + Outlet)' },
  { path: '/admin/users', name: 'Users', parent: 'Admin',
    contextProvided: { userFilter: 'active' },
    renders: 'UserList' },
  { path: '/admin/users/$id', name: 'UserDetail', parent: 'Users',
    contextProvided: { detailTab: 'overview' },
    renders: 'UserDetail' }
];

// matchPath: a $param segment matches exactly ONE url segment (like TanStack).
function matchPath(pattern, pathname) {
  var patternParts = pattern.split('/').filter(Boolean);
  var pathParts = pathname.split('/').filter(Boolean);
  if (patternParts.length !== pathParts.length) return false;
  for (var i = 0; i < patternParts.length; i++) {
    if (patternParts[i].charAt(0) === '$') continue; // $id skips the segment
    if (patternParts[i] !== pathParts[i]) return false;
  }
  return true;
}

// The deepest route whose pattern fits the pathname = the matched LEAF.
// Walk the ranked list top-down; first (deepest) match wins.
function findLeaf(pathname) {
  for (var i = routeHierarchy.length - 1; i >= 0; i--) {
    if (matchPath(routeHierarchy[i].path, pathname)) return routeHierarchy[i];
  }
  return routeHierarchy[0];
}

// Walk parents upward → ordered [Root, …, leaf]. This is the rendered chain.
function buildChain(leaf) {
  var chain = [];
  var node = leaf;
  while (node) {
    chain.unshift(node);
    var pname = node.parent;
    node = pname
      ? routeHierarchy.filter(function (r) { return r.name === pname; })[0]
      : null;
  }
  return chain;
}

// Each level adds its context to the inherited parent context (top-down merge).
function accumulateContext(chain) {
  var ctx = {};
  chain.forEach(function (route) {
    Object.keys(route.contextProvided).forEach(function (k) {
      ctx[k] = route.contextProvided[k];
    });
  });
  return ctx;
}

// Tree depth = how many ancestors (for indentation).
function depthOf(route) {
  var d = 0;
  var node = route;
  while (node.parent) {
    d++;
    node = routeHierarchy.filter(function (r) { return r.name === node.parent; })[0];
  }
  return d;
}

function NestedContextDemo() {
  var state = React.useState('/admin/users/42');
  var activePath = state[0];
  var setActivePath = state[1];

  var leaf = findLeaf(activePath);
  var chain = buildChain(leaf);
  var ctx = accumulateContext(chain);
  var chainNames = chain.map(function (r) { return r.name; });
  var ctxKeys = Object.keys(ctx);

  return (
    <div className="max-w-3xl mx-auto space-y-4">

      {/* active path readout */}
      <div data-testid="active-path" data-path={activePath} className="text-xs text-[#8b949e]">
        current path: <span className="text-[#61dafb] font-bold">{activePath}</span>
      </div>

      {/* 1 · route tree — click to navigate, matched chain is highlighted */}
      <div>
        <div className="text-xs uppercase tracking-wide text-[#61dafb] mb-2">route tree (click a route)</div>
        <div className="bg-[#0d1117] border border-[#30363d] rounded p-3 space-y-1">
          {routeHierarchy.map(function (route) {
            var d = depthOf(route);
            var inChain = chainNames.indexOf(route.name) >= 0;
            var isLeaf = route.name === leaf.name;
            return (
              <div
                key={route.path}
                data-testid="route-node"
                data-path={route.path}
                data-name={route.name}
                className={"px-3 py-2 rounded text-sm cursor-pointer transition-colors border " + (inChain ? 'border-[#61dafb] bg-[#61dafb]/10' : 'border-transparent bg-[#161b22] hover:border-[#30363d]')}
                style={{ paddingLeft: 12 + d * 22 }}
                onClick={function () { setActivePath(route.path); }}
              >
                <span className={"font-bold " + (inChain ? 'text-[#61dafb]' : 'text-[#e6edf3]')}>{route.name}</span>
                {' '}
                <code className="text-[#8b949e]">{route.path}</code>
                {isLeaf ? <span className="ml-2 text-[10px] text-[#2ecc71]">← matched leaf</span> : null}
                {inChain ? <span className="ml-2 text-[10px] text-[#61dafb]">✓ in chain</span> : null}
              </div>
            );
          })}
        </div>
      </div>

      {/* 2 · matched chain (Root → leaf) */}
      <div>
        <div className="text-xs uppercase tracking-wide text-[#61dafb] mb-2">matched chain (ancestor chain = rendered layout stack)</div>
        <div data-testid="chain" data-chain={chainNames.join(' > ')} className="bg-[#0d1117] border border-[#30363d] rounded p-3 text-sm flex flex-wrap items-center gap-1">
          {chain.map(function (r, i) {
            var isLast = i === chain.length - 1;
            return (
              <span key={r.name} className="flex items-center gap-1">
                <span className={"px-2 py-1 rounded " + (isLast ? 'bg-[#61dafb] text-[#0d1117] font-bold' : 'text-[#61dafb] border border-[#30363d]')}>{r.name}</span>
                {isLast ? null : <span className="text-[#8b949e]">→</span>}
              </span>
            );
          })}
        </div>
      </div>

      {/* 3 · accumulated context — merged top-down */}
      <div>
        <div className="text-xs uppercase tracking-wide text-[#61dafb] mb-2">accumulated route context (beforeLoad merged down the chain)</div>
        <div data-testid="context" data-json={JSON.stringify(ctx)} className="bg-[#0d1117] border border-[#30363d] rounded p-3 text-sm">
          <span className="text-[#8b949e]">{'{'}</span>
          <div className="ml-4 space-y-1">
            {ctxKeys.map(function (k) {
              var who = chain.filter(function (r) { return typeof r.contextProvided[k] !== 'undefined'; })[0];
              return (
                <div key={k}>
                  <span className="text-[#61dafb]">{k}</span>
                  <span className="text-[#8b949e]">: </span>
                  <span className="text-[#2ecc71]">{JSON.stringify(ctx[k])}</span>
                  <span className="text-[#8b949e] text-[11px]">  ← {who ? who.name : '?'}</span>
                </div>
              );
            })}
          </div>
          <span className="text-[#8b949e]">{'}'}</span>
        </div>
      </div>

      {/* 4 · <Outlet/> composition — parent layout wraps the child */}
      <div>
        <div className="text-xs uppercase tracking-wide text-[#61dafb] mb-2">{'<Outlet/>'} composition (parent renders layout + Outlet, child renders inside)</div>
        <div className="bg-[#0d1117] border border-[#30363d] rounded p-3">
          {chain.map(function (r, i) {
            var isLast = i === chain.length - 1;
            var keys = Object.keys(r.contextProvided);
            return (
              <div key={r.name} className="border border-[#30363d] rounded p-2 mb-2" style={{ marginLeft: i * 16 }}>
                <div className="flex items-center gap-2 text-xs">
                  <span className="text-[#61dafb] font-bold">{r.name}</span>
                  <span className="text-[#8b949e]">{r.renders}</span>
                </div>
                <div className="text-[11px] text-[#8b949e] mt-1">
                  provides: {keys.length ? keys.map(function (k) { return k + '=' + JSON.stringify(r.contextProvided[k]); }).join(', ') : '(none)'}
                </div>
                {isLast ? null : <div className="text-[11px] text-[#61dafb] mt-1">{'<Outlet/>'} ↓</div>}
              </div>
            );
          })}
        </div>
      </div>

    </div>
  );
}

createRoot(document.getElementById('root')).render(<NestedContextDemo/>);

2 · Babel compiles JSX → element tree

<NestedContextDemo/> becomes React.createElement(NestedContextDemo). Clicking a route calls setActivePath → re-render → findLeaf + buildChain + accumulateContext rebuild the chain and merged context from scratch.

// (hit "compile & render" to see Babel's output)

3 · live React (nested chain + context accumulation, proven)

Click any route in the tree. The gold-check drives it directly: default /admin/users/42 → asserts chain [Root, Admin, Users, UserDetail] with all 5 context keys, then CLICKS /admin → asserts the chain collapses to [Root, Admin] and the context loses userFilter/detailTab. That proves matching, chain construction, and the top-down context merge all work.

routes: — · gold: /admin/users/42→[Root,Admin,Users,UserDetail]{5 keys} → /admin→[Root,Admin]{3 keys}

intent → pattern

intent	pattern	why
wrap child routes in a layout	parent `component` renders `<Outlet/>`	the Outlet is where the matched child renders — that is nested rendering
provide data to a route + descendants	`beforeLoad: ({'{ context }'}) => ({'{ ...context, ... }}')`	spread inherited context then add your keys — returns the merged object
read parent data in a child loader	`loader: ({'{ context }'}) => fetchUsers(context.adminMode)`	context is already merged by the time the loader runs
opt OUT of nesting	name the file `_path.tsx` (pathless layout) or un-nest via `_`	renders its own component without the parent layout / Outlet
access the accumulated context	`Route.useMatch().context` / `useLoaderData()`	type is the union of every ancestor's `beforeLoad` return type