What is the mental model for client-side routing?
History, soft navigation, data loading, pending UI, scroll restoration, and the difference between a URL change and a full document load.
Useful prerequisites
A client-side route change can update the URL and replace part of the page without asking the browser to load a new document. That feels instant, but the application now owns work the browser normally handles: history, loading states, scroll position, focus and failed navigation. A router is coordinating all of those pieces, not merely swapping components.
A client-side route change can update the URL and replace part of the page without asking the browser to load a new document. That feels instant, but the application now owns work the browser normally handles: history, loading states, scroll position, focus and failed navigation. A router is coordinating all of those pieces, not merely swapping components.
The quick version
Client-side routing intercepts navigation, updates the URL via the History API, renders the matching view without a full document load, and (ideally) manages data loading, pending states, scroll position, and focus. The URL remains the source of truth for where the user is; the router is the machinery that keeps the UI and the history stack in sync with that URL.
Build the mental model
A traditional multi-page app treats every navigation as a full document request. The browser handles history, scroll restoration, and the loading indicator. Accessibility and focus largely follow the new document.
A client-side router takes over part of that job:
- User clicks a link or the app calls
navigate. - The router prevents the default full navigation (when it is an internal link).
- It pushes or replaces an entry in the history stack.
- It figures out which route matched.
- It renders the corresponding UI, often while data is still loading.
- It should restore or reset scroll and move focus in a way that matches user expectations.
The hard part is not matching /users/:id. The hard part is everything that the browser used to do for free and that users still expect: back button behaviour, scroll position, loading feedback, and not losing context.
Soft navigation vs full navigation
Soft navigation — URL changes, same document, JavaScript updates the view. Fast when done well. You own loading UI, error UI, scroll, and focus.
Full navigation — normal browser document load. You get the browser’s loading indicator, scroll restoration (with caveats), and a clean focus start. You lose SPA continuity.
Good apps use soft navigation for the common internal cases and still allow full navigation when it is the right tool (external links, hard reloads, some auth redirects, progressive enhancement fallbacks).
Data loading and pending UI
Once navigation is soft, data loading becomes part of the route transition. Two broad approaches:
-
Render immediately, load data in the view.
The new screen appears fast; each component fetches what it needs. Easy to start, easy to create waterfalls and duplicated requests. -
Load data as part of the route.
The router (or a framework layer on top of it) knows what data the route needs and kicks off loads before or while rendering. Enables better pending states and parallel fetching, at the cost of more upfront structure.
Pending UI is not optional if the data is not already in cache. Users need a clear signal that navigation happened and content is coming. A blank screen or a frozen previous view both feel broken.
Race conditions appear here too. If the user clicks three links quickly, only the latest navigation should win. Cancel or ignore stale loads the same way you would for any other request lifecycle.
Scroll restoration and focus
Browsers try to restore scroll on back/forward for full navigations. In a soft navigation world you must decide:
- Forward navigation — usually scroll to top (or to a hash target).
- Back/forward — restore the previous scroll position if you can, or at least avoid surprising jumps.
- Same-route updates (query params, tabs) — often preserve scroll unless the change is a clear “new content” action.
Focus should move to a sensible place after navigation — often the main content landmark or the primary heading of the new view — so keyboard and screen-reader users are not left on a link that is no longer meaningful.
These details are easy to postpone and expensive to retrofit once users have already learned that “the back button loses my place.”
History stack discipline
pushwhen the user should be able to go back to the previous screen.replacewhen the current entry should be overwritten (login redirect after success, wizard step that should not pile up, fixing a default query param).- Avoid creating history entries for purely visual toggles that the user does not think of as “pages.”
Deep links and shareable URLs still matter. If the only way to reach a state is a sequence of clicks with no URL representation, you have built a private application, not a web one.
Concrete implementation sketch
// Conceptual — not a specific library
async function navigate(to: string, opts?: { replace?: boolean }) {
const url = new URL(to, window.location.origin);
// 1. Match route
const match = matchRoute(url.pathname);
// 2. Start data loads (and keep a sequence token)
const sequence = ++navSequence;
const dataPromise = loadRouteData(match);
// 3. Update history
if (opts?.replace) history.replaceState(null, '', url);
else history.pushState(null, '', url);
// 4. Show pending UI if needed
setPending(true);
try {
const data = await dataPromise;
if (sequence !== navSequence) return; // stale navigation
renderRoute(match, data);
restoreScroll(url);
moveFocusToMain();
} catch (error) {
if (sequence !== navSequence) return;
renderRouteError(error);
} finally {
if (sequence === navSequence) setPending(false);
}
}
Real routers do more (nested routes, loaders, actions, blocking, etc.), but the mental model stays the same: URL change, data, render, scroll, focus, and latest-navigation-wins.
Where it gets tricky
Back button after a redirect.
If login redirects to /dashboard with replace, the user should not land back on the login page when they press back. Getting this wrong is a common auth-flow bug.
Hash and query-only changes.
Changing only the hash or a filter query param may or may not deserve a full route re-render and scroll reset. Make that choice explicit.
External links and download links.
Do not intercept them. Let the browser handle them.
Slow networks and the “back” button during a pending navigation.
The user can press back while a soft navigation is still loading. Your sequence token and history handling need to stay consistent.
SSR / hydration.
The first load is a full document. Client-side routing takes over after hydration. The first paint and the first soft navigation must not produce a flash of wrong content or a double fetch if you can avoid it.
A common misunderstandings
-
“Client-side routing is just matching paths to components.”
That is the easy part. History, data, scroll, focus, and pending states are the product surface. -
“SPAs do not need real URLs.”
They do, if you want shareability, bookmarks, and sane back-button behaviour. -
“The framework handles scroll restoration, so I can ignore it.”
Frameworks give you tools. The policy (when to restore, when to reset) is still yours.
What this changes in an application
Users judge navigation by feel: did the back button do what I expected, did I keep my scroll position, did something clearly happen when I clicked, can I share this URL? Teams that treat routing as pure component swapping rediscover these requirements later, usually under time pressure. A clear mental model up front keeps the behaviour predictable and the implementation debuggable.
Questions worth exploring next
- How would you cancel in-flight route loads when the user navigates again?
- When do you choose
pushvsreplace? - How does nested routing change data loading and error boundaries?
- What should happen to focus after a soft navigation?
References and next steps
- MDN — History API — the platform primitives.
- MDN — Navigation API — newer platform support for intercepting navigation.
- Framework router docs (React Router, TanStack Router, SvelteKit, Next.js App Router, etc.) — read them for the concrete trade-offs each one chose around loaders, pending UI, and scroll.