Advanced Router Patterns — React Deep Dive

three gates around every navigation

A route is more than a component. The router runs a lifecycle around each navigation: beforeLoad can throw redirect() (the auth gate), a blocker can pause or cancel the transition (the unsaved-changes gate), and masking decides which URL lands in history vs. which route actually renders. The order matters: block check → auth check → commit URL → render.

pattern	gate	API	what it can do
Authenticated route	before navigation commits	`beforeLoad` + `throw redirect()`	abort → send to /login, remember the target, redirect back after auth
Navigation blocking	before navigation commits	`useBlocker({ shouldBlockFn, withResolver })`	pause → show "unsaved changes?" UI → `proceed()` or `reset()`
Location masking	at commit (history write)	`<Link mask={{ to }}>` / `createRouteMask()`	render route A, but persist a clean URL B to history + the address bar

1 · the auth + blocking simulator (edit me)

// Simulated router context — mirrors TanStack Router's `context` object
// that beforeLoad reads. In a real app this comes from your auth provider.
var auth = { user: null };

// Simulated routes registry: which routes require auth, and what the
// "clean" masked URL would be (location masking lives here in real apps).
var ROUTES = {
  home:      { path: '/',          requiresAuth: false, mask: null },
  dashboard: { path: '/dashboard', requiresAuth: true,  mask: null },
  editor:    { path: '/editor',    requiresAuth: false, mask: null },
  login:     { path: '/login',     requiresAuth: false, mask: null }
};

function AuthDemo() {
  // The four pieces of router state this gate-machine tracks:
  var _React$useState = React.useState(null),
      user = _React$useState[0],
      setUser = _React$useState[1];
  var _React$useState2 = React.useState('home'),
      route = _React$useState2[0],
      setRoute = _React$useState2[1];
  var _React$useState3 = React.useState(null),
      loginRedirect = _React$useState3[0],
      setLoginRedirect = _React$useState3[1];
  var _React$useState4 = React.useState(false),
      hasUnsavedChanges = _React$useState4[0],
      setHasUnsavedChanges = _React$useState4[1];
  var _React$useState5 = React.useState(null),
      blockedTarget = _React$useState5[0],
      setBlockedTarget = _React$useState5[1];

  // ── navigate(): the gate pipeline runs here ──────────────────────────
  // GATE 1 — navigation blocking (useBlocker equivalent):
  //   if leaving editor with unsaved changes, PAUSE and remember the target.
  // GATE 2 — auth (beforeLoad equivalent):
  //   if the target requires auth and there's no user, redirect to /login
  //   and remember where they wanted to go (loginRedirect).
  // COMMIT — clear blockers, swap the route.
  function navigate(target) {
    // GATE 1: blocker
    if (hasUnsavedChanges && target !== route) {
      setBlockedTarget(target);
      return false;
    }
    // GATE 2: auth
    if (ROUTES[target].requiresAuth && !user) {
      setLoginRedirect(target);  // remember destination → redirect back later
      setRoute('login');
      return false;
    }
    setBlockedTarget(null);
    setRoute(target);
    return true;
  }

  function login() {
    setUser('admin');
    auth.user = 'admin';
    // beforeLoad's `search.redirect` is honored here: go back to the
    // page the user originally wanted, else default to dashboard.
    if (loginRedirect) {
      setRoute(loginRedirect);
      setLoginRedirect(null);
    } else {
      setRoute('dashboard');
    }
  }

  function logout() {
    setUser(null);
    auth.user = null;
    setLoginRedirect(null);
    setRoute('home');
  }

  // "Force navigate" = the user confirmed the unsaved-changes prompt.
  // Mirrors useBlocker's `proceed()` — drops the block and commits.
  function forceNavigate() {
    if (blockedTarget) {
      var target = blockedTarget;
      setHasUnsavedChanges(false);  // resolve the blocker
      setBlockedTarget(null);
      // Re-run the pipeline with the blocker cleared. Auth still applies.
      if (ROUTES[target].requiresAuth && !user) {
        setLoginRedirect(target);
        setRoute('login');
      } else {
        setRoute(target);
      }
    }
  }

  function cancelBlock() {
    setBlockedTarget(null);  // mirrors useBlocker's `reset()`
  }

  function toggleUnsaved() {
    setHasUnsavedChanges(!hasUnsavedChanges);
  }

  var navBtns = [
    { key: 'home', label: 'Home' },
    { key: 'dashboard', label: 'Dashboard (auth)' },
    { key: 'editor', label: 'Editor (blocker)' }
  ];

  var ROUTE_COPY = {
    home: 'Public landing page — no auth, no blocker.',
    dashboard: 'Private area — beforeLoad threw redirect() to /login until you logged in.',
    editor: 'Editable area — toggle "unsaved changes" then try to leave.',
    login: 'Login screen — submitting sends you back to where you were going.'
  };

  return (
    <div className="max-w-2xl mx-auto p-5 bg-[#161b22] rounded-xl border border-[#30363d]">
      <h2 className="text-lg font-bold text-[#61dafb] m-0 mb-4">Router: gate simulator</h2>

      {/* state readout — what the gold-check inspects */}
      <div className="grid grid-cols-2 gap-3 mb-4 text-xs">
        <div className="p-3 rounded border border-[#30363d] bg-[#0d1117]">
          <div className="text-[#8b949e] uppercase tracking-wide mb-1">auth (context.user)</div>
          <div data-testid="user" className="font-bold text-[#e6edf3]">
            {user ? '✓ ' + user : '✗ logged out'}
          </div>
        </div>
        <div className="p-3 rounded border border-[#30363d] bg-[#0d1117]">
          <div className="text-[#8b949e] uppercase tracking-wide mb-1">current route</div>
          <div data-testid="route" className="font-bold text-[#61dafb]">{route}</div>
        </div>
        <div className="p-3 rounded border border-[#30363d] bg-[#0d1117]">
          <div className="text-[#8b949e] uppercase tracking-wide mb-1">unsaved changes</div>
          <div data-testid="unsaved" data-on={hasUnsavedChanges ? 'true' : 'false'} className="font-bold">
            <span className={hasUnsavedChanges ? 'text-[#f1c40f]' : 'text-[#8b949e]'}>
              {hasUnsavedChanges ? '⚠ dirty' : '○ clean'}
            </span>
          </div>
        </div>
        <div className="p-3 rounded border border-[#30363d] bg-[#0d1117]">
          <div className="text-[#8b949e] uppercase tracking-wide mb-1">login redirect</div>
          <div data-testid="redirect" className="font-bold text-[#8b949e]">
            {loginRedirect || '—'}
          </div>
        </div>
      </div>

      {/* navigation buttons */}
      <div className="flex flex-wrap gap-2 mb-4">
        {navBtns.map(function (b) {
          var active = route === b.key;
          return (
            <button
              key={b.key}
              data-testid={'nav-' + b.key}
              className={"px-3 py-2 rounded text-sm font-bold border " + (active ? 'bg-[#61dafb] text-[#0d1117] border-[#61dafb]' : 'bg-transparent text-[#61dafb] border-[#30363d] hover:border-[#61dafb]')}
              onClick={function () { navigate(b.key); }}
            >
              {b.label}
            </button>
          );
        })}
        <div className="ml-auto flex gap-2">
          {user ? (
            <button data-testid="logout" className="px-3 py-2 rounded text-sm font-bold border border-[#e74c3c] text-[#e74c3c] hover:bg-[rgba(231,76,60,.12)]" onClick={logout}>
              Logout
            </button>
          ) : (
            <button data-testid="login-btn" className={"px-3 py-2 rounded text-sm font-bold border " + (route === 'login' ? 'bg-[#2ecc71] text-[#0d1117] border-[#2ecc71]' : 'border-[#2ecc71] text-[#2ecc71] hover:bg-[rgba(46,204,113,.12)]')} onClick={login}>
              ▶ Login as admin
            </button>
          )}
        </div>
      </div>

      {/* editor-only: unsaved-changes toggle */}
      {route === 'editor' ? (
        <div className="mb-4 p-3 rounded border border-[#30363d] bg-[#0d1117]">
          <label className="flex items-center gap-2 text-sm cursor-pointer select-none">
            <input data-testid="toggle-unsaved" type="checkbox" checked={hasUnsavedChanges} onChange={toggleUnsaved} className="w-4 h-4 accent-[#f1c40f]" />
            <span className="text-[#e6edf3]">Toggle unsaved changes (enables the blocker)</span>
          </label>
        </div>
      ) : null}

      {/* route content */}
      <div data-testid="content" className="p-4 rounded border border-dashed border-[#30363d] bg-[#0b0f14] text-sm text-[#8b949e] mb-4">
        <div className="text-[11px] uppercase tracking-wide text-[#61dafb] mb-1">rendering: {ROUTES[route].path}</div>
        {ROUTE_COPY[route]}
      </div>

      {/* blocker prompt — shown when a navigation is paused */}
      {blockedTarget ? (
        <div data-testid="blocked" className="p-4 rounded border border-[#f1c40f] bg-[rgba(241,196,15,.08)] mb-4">
          <div className="text-[#f1c40f] font-bold text-sm mb-1">⚠ Navigation blocked</div>
          <div className="text-[#e6edf3] text-sm mb-3">
            You have unsaved changes. Leave editor for
            <span data-testid="blocked-target" className="text-[#61dafb] font-bold mx-1">{blockedTarget}</span>?
          </div>
          <div className="flex gap-2">
            <button data-testid="force-navigate" className="px-3 py-1.5 rounded text-xs font-bold bg-[#f1c40f] text-[#0d1117] hover:opacity-80" onClick={forceNavigate}>
              Force navigate (proceed)
            </button>
            <button data-testid="cancel-block" className="px-3 py-1.5 rounded text-xs font-bold border border-[#30363d] text-[#8b949e] hover:text-[#e6edf3]" onClick={cancelBlock}>
              Stay here (reset)
            </button>
          </div>
        </div>
      ) : null}
    </div>
  );
}

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

2 · Babel compiles JSX → element tree

<AuthDemo/> becomes React.createElement(AuthDemo). navigate() runs the two gates in order — blocker first (pause + remember target), then auth (redirect to /login + remember destination). The blocker's proceed/reset map to forceNavigate/ cancelBlock.

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

3 · live React (the gate pipeline, proven)

Click Dashboard while logged out → you're sent to /login and the destination is remembered. Login sends you back. In the Editor, toggle unsaved changes and try to leave — navigation pauses. Force navigate resolves the block. The gold-check walks all six steps automatically.

route: — · user: — · gold: home→login→dashboard→editor→block→force→home

intent → pattern

intent	pattern	why
require login for a route	`beforeLoad` + `throw redirect({'{'}to:'/login', search:{'{'}redirect: location.pathname{'}'}{'}'})`	redirect aborts the navigation; search param remembers the target
redirect back after login	read `search.redirect` on the login route → `navigate({'{'}to: redirect{'}'})`	the "remember where I was going" round-trip
block leaving with unsaved changes	`useBlocker({'{'}shouldBlockFn: () ={'>'} isDirty, withResolver: true{'}'})`	returns `{'{'}proceed, reset, status{'}'}` — drive a custom dialog
also block tab close / reload	`enableBeforeUnload: isDirty` on the blocker	registers the native `beforeunload` handler conditionally
show a clean URL, render a different route	`<Link to="/photos/$id/modal" mask={'{'}to:'/photos/$id'{'}'}>`	address bar + history show the mask; router renders the real route
shareable masked URLs app-wide	`createRouteMask({'{'}routeTree, from, to{'}'})` → router `routeMasks`	declare once; every matching `navigate` is masked