# Client-Side Routing

Client-side routing maps URLs to browser-rendered views while changing history without loading a new document for each transition.

- Type: practice
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-09-23
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/client-side-routing/>)

## What it means

Client-side routing intercepts eligible navigation inside a web application, uses browser history APIs to update the URL, and renders the matching view without a full document navigation. A robust router still treats URLs as durable addresses and preserves expected link, history, focus, scroll, and server fallback behavior.

## Why it matters

Routing makes an application linkable and navigable, but taking over document navigation also transfers browser responsibilities to application code. Failures affect back and forward controls, accessibility, analytics, recovery, and direct entry to routes.

## When to use it

Use client-side routing when transitions benefit from retained application state or partial rendering. Keep ordinary links and server-resolvable URLs, and prefer standard navigation when the transition does not need a persistent client runtime.

## How it works

1. Define stable URL patterns and the views and data associated with them.
2. Intercept only same-application navigations that the router can handle safely.
3. Update history with pushState or replaceState and render the matched view.
4. Handle popstate so browser back and forward controls restore the correct state.
5. Manage titles, focus, announcements, scroll, errors, and direct-load server fallbacks.

## A practical example

A support console keeps an active call connected while an agent moves from a customer profile to an order. Each view has a shareable URL, back restores the prior view, and focus moves to the new page heading.

## Where it breaks

Routers add code and state synchronization, and their transitions can fail differently from document loads. URL and UI state can diverge, while reloads still require the server to recognize every public route.

## Common mistakes

- Using click handlers on non-link elements instead of real links.
- Changing content without updating the URL, title, focus, or history.
- Breaking modified clicks, downloads, external links, or opening in a new tab.
- Returning a server error when a user loads a client route directly.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/client-side-routing/#visualization-client-side-routing>)

## Sources

1. [History API](<https://developer.mozilla.org/en-US/docs/Web/API/History_API>) — MDN Web Docs · Official technical documentation
2. [HTML Standard: Session History and Navigation](<https://html.spec.whatwg.org/multipage/nav-history-apis.html>) — WHATWG · Living web standard

## Related topics

- [Single-Page Application \(SPA\)](<https://wiki.soroush.uk/topic/single-page-application/>)
- [Navigation Design](<https://wiki.soroush.uk/topic/navigation-design/>)
- [Document Object Model \(DOM\)](<https://wiki.soroush.uk/topic/document-object-model/>)
