# Client-Side Rendering \(CSR\)

Client-side rendering uses JavaScript in the browser to create or update a route's main interface after its document arrives.

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

## What it means

Client-side rendering \(CSR\) produces a view primarily in the browser. An initial HTML document loads JavaScript, the application obtains data, and code creates or changes DOM content. CSR can describe an initial route or later transitions; it does not require that every part of the product use the same rendering method.

## Why it matters

CSR enables rich stateful interfaces and moves rendering capacity to users' devices, but content and interaction may depend on script download, parsing, execution, and data requests. These costs vary sharply with device and network conditions.

## When to use it

Use CSR for private, interaction-heavy views where data is naturally fetched after authentication and persistent browser state provides value. Avoid making essential content depend on a large client runtime when server or static HTML can deliver it more reliably.

## How it works

1. The server returns a document shell and references to scripts and styles.
2. The browser downloads, parses, and executes the application code.
3. Client code establishes state and requests any data needed for the route.
4. The application creates or updates DOM nodes for the current view.
5. Later state and route changes trigger targeted client renders.

## A practical example

An internal analytics workspace renders charts after the signed-in browser obtains user-specific data. The team keeps the sign-in and error pages server-rendered, splits the chart code, and provides clear loading and retry states.

## Where it breaks

Initial content can be delayed by JavaScript and request waterfalls, low-powered devices pay execution cost, and script failure can leave an empty shell. Search and sharing behavior may require separate handling, and complex client state creates debugging overhead.

## Common mistakes

- Assuming client rendering is fast because navigation feels quick on a development laptop.
- Shipping one large bundle before showing essential content.
- Leaving an empty page when scripts or data requests fail.
- Using CSR for every route instead of choosing rendering per user need.

## Visualization

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

## Sources

1. [Rendering on the Web](<https://web.dev/articles/rendering-on-the-web>) — web.dev · Official technical guidance
2. [Client-side web APIs](<https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Client-side_APIs/Introduction>) — MDN Web Docs · Official technical documentation

## Related topics

- [Server-Side Rendering \(SSR\)](<https://wiki.soroush.uk/topic/server-side-rendering/>)
- [Single-Page Application \(SPA\)](<https://wiki.soroush.uk/topic/single-page-application/>)
- [JavaScript Bundle](<https://wiki.soroush.uk/topic/javascript-bundle/>)
