practiceEngineering & architecture

Client-Side Routing

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

Download Markdown (.md)

01What 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.[1][2]

URL changes without replacing the document Intercept safe navigation, render the route, and preserve browser expectations
  1. 01Eligible linkSame application and safely interceptable
  2. 02Update historypushState or replaceState
  3. 03Match + renderView and route data
  4. 04Restore page behaviorTitle, focus, announcement, scroll
  5. 05Back or forwardpopstate restores correct route state

Durable URLs still need direct-load server fallback, while titles, focus, announcements, scroll, errors, and history require deliberate restoration.

02Why 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.

03When 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.

04How 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.

05A practical example

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.

06Where 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.

07Sources

  1. History APIMDN Web Docs · Official technical documentationHistory API
  2. HTML Standard: Session History and NavigationWHATWG · Living web standardHTML Standard: Session History and Navigation
View saved topics

Start typing to search titles, definitions, categories, and frameworks.