Skip to content

Blazor hosting models and render modes

The same Razor component can run in very different places: on the web server, producing plain HTML; on the server while staying interactive over a WebSocket connection; in the browser on a WebAssembly build of .NET; or inside a native desktop or mobile app. Choosing where each part of an app runs is the most consequential Blazor design decision, because it determines latency, server load, download size, offline support and what code is exposed to users. Since .NET 8 the choice is made per component through render modes in a Blazor Web App, rather than once per app.

Facts on this page follow the .NET 10 and .NET 11 versions of the ASP.NET Core documentation (.NET 10 is the current LTS release; .NET 11, an STS release, shipped in November 2026). The sample is a Blazor Web App created with dotnet new blazor --interactivity Auto --all-interactive false --empty on the .NET SDK 10.0.115, built and run locally, and requested with curl.

Topic Use it to
Blazor Web Apps and render modes Understand the four render modes and how to apply them.
Static server rendering Serve fast HTML pages with forms and streaming, without a live connection.
Interactive Server Run interactive UI on the server over SignalR.
Interactive WebAssembly Run interactive UI in the browser on .NET for WebAssembly.
Interactive Auto Start on the server, then switch to WebAssembly once it is downloaded.
Blazor Hybrid Reuse Razor components in native .NET MAUI, WPF or Windows Forms apps.

A Blazor Web App is an ASP.NET Core app in which every component has a render mode: Static Server (static SSR, the default, not interactive), Interactive Server (interactive server-side rendering over SignalR), Interactive WebAssembly (client-side rendering in the browser) or Interactive Auto (Server first, WebAssembly on later visits). The project template wires up the services and endpoints for the modes you choose in Program.cs, and when WebAssembly is involved it creates a second .Client project for the components that must be able to run in the browser.

You apply a mode with the @rendermode directive on a component instance (<OrderNotes @rendermode="InteractiveServer" />), on a component definition (@rendermode InteractiveServer at the top of the file), or globally on <Routes> and <HeadOutlet> in App.razor, which makes the whole app interactive. Modes propagate down the tree: children of an interactive component share its mode, a child cannot switch to a different interactive mode, and parameters passed from a static parent into an interactive child must be JSON-serializable, so you cannot pass RenderFragment child content across that boundary. Interactive components are prerendered on the server by default, so users see HTML before interactivity starts. RendererInfo (.NET 9 and later) tells a component where it is running and whether it is interactive right now.

// OrdersPortal/Program.cs (as generated by the template)
using OrdersPortal.Components;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddRazorComponents()
.AddInteractiveServerComponents()
.AddInteractiveWebAssemblyComponents();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseWebAssemblyDebugging();
}
else
{
app.UseExceptionHandler("/Error", createScopeForErrors: true);
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}
app.UseStatusCodePagesWithReExecute("/not-found", createScopeForStatusCodePages: true);
app.UseHttpsRedirection();
app.UseAntiforgery();
app.MapStaticAssets();
app.MapRazorComponents<App>()
.AddInteractiveServerRenderMode()
.AddInteractiveWebAssemblyRenderMode()
.AddAdditionalAssemblies(typeof(OrdersPortal.Client._Imports).Assembly);
app.Run();
@* OrdersPortal.Client/RenderModeBadge.razor *@
@* Lives in the .Client project so it can run on WebAssembly as well as on the server. *@
<p class="render-info">
@Label: rendered by @RendererInfo.Name, interactive: @RendererInfo.IsInteractive,
assigned mode: @(AssignedRenderMode?.GetType().Name ?? "none (static)")
</p>
<button type="button" @onclick="() => clicks++" disabled="@(!RendererInfo.IsInteractive)">Clicked @clicks times</button>
@code {
[Parameter] public string Label { get; set; } = "";
private int clicks;
}
@* OrdersPortal/Components/Pages/Orders.razor *@
@page "/orders"
@attribute [StreamRendering]
@using OrdersPortal.Client
<PageTitle>Open orders</PageTitle>
<h1>Open orders</h1>
@if (orders is null)
{
<p>Loading orders...</p>
}
else
{
<ul>
@foreach (var order in orders)
{
<li>Order @order.Id for @order.Customer</li>
}
</ul>
}
<RenderModeBadge Label="Static" />
<RenderModeBadge Label="Server" @rendermode="InteractiveServer" />
<RenderModeBadge Label="WebAssembly" @rendermode="InteractiveWebAssembly" />
<RenderModeBadge Label="Auto" @rendermode="InteractiveAuto" />
@code {
private record OrderRow(int Id, string Customer);
private List<OrderRow>? orders;
protected override async Task OnInitializedAsync()
{
await Task.Delay(300); // stand-in for a database query; the page streams "Loading..." first
orders = [new(1001, "Ada Lopez"), new(1002, "Ben Ortiz")];
}
}

Requesting the page with curl -N http://127.0.0.1:5187/orders (response shortened: layout, scripts and the serialized <!--Blazor:{...}--> component markers removed):

<h1>Open orders</h1><p>Loading orders...</p>
<p class="render-info">Static: rendered by Static, interactive: False,
assigned mode: none (static)</p>
<button type="button" disabled>Clicked 0 times</button>
<p class="render-info">Server: rendered by Static, interactive: False,
assigned mode: InteractiveServerRenderMode</p>
<button type="button" disabled>Clicked 0 times</button>
<p class="render-info">WebAssembly: rendered by Static, interactive: False,
assigned mode: InteractiveWebAssemblyRenderMode</p>
<button type="button" disabled>Clicked 0 times</button>
<p class="render-info">Auto: rendered by Static, interactive: False,
assigned mode: InteractiveAutoRenderMode</p>
<button type="button" disabled>Clicked 0 times</button>
...
<blazor-ssr><template blazor-component-id="15">
<h1>Open orders</h1><ul><li>Order 1001 for Ada Lopez</li><li>Order 1002 for Ben Ortiz</li></ul>
...

Two things are visible in the raw response. All four badges were prerendered as static HTML, which is why even the interactive ones report Static and interactive: False; in a browser, the Server, WebAssembly and Auto badges then re-render as Server or WebAssembly with an enabled button once their runtime starts. And because of [StreamRendering], the first bytes contained “Loading orders…” and the finished list arrived later in the same response inside <blazor-ssr>, which the Blazor script patches into the page.

Pitfalls:

  • Mixing interactive modes in one subtree. A Server component cannot be a child of a WebAssembly component; make siblings with different modes instead.
  • Passing ChildContent from a static parent to an interactive child fails because render fragments cannot be serialized.
  • Disabled-looking UI during prerendering. Buttons do nothing until interactivity starts; show that state (as the sample does) or disable prerendering for components where it confuses users.

Static SSR is the default render mode: the component renders once on the server for each HTTP request and the result is sent as HTML, like Razor Pages or MVC. There is no persistent connection and no .NET in the browser, so pages are cheap to serve, fast to first paint and easy to cache. .NET 11 adds a CacheView component that caches the output of an expensive subtree. Static pages still get a lot of interactivity from the platform: enhanced navigation intercepts links and form posts and patches the DOM instead of reloading the page, streaming rendering ([StreamRendering]) sends placeholder content immediately and streams the rest as async work completes, and EditForm with FormName and [SupplyParameterFromForm] handles posts. In .NET 11, static SSR forms also get client-side validation feedback from the model’s data annotations without a round trip.

Choose static SSR for content pages, catalogs, dashboards that mostly display data, and forms, and add interactive islands only where a component genuinely needs per-keystroke or per-click behavior.

Pitfalls:

  • @onclick on a static component does nothing. There is no runtime to handle it; use a form, a link, or give the component an interactive mode.
  • Missing FormName. Forms posted from static components need a unique name, or the post fails when it arrives.
  • Assuming state survives between requests. Each request creates new component instances; keep state in the URL, the form, a cookie or the database.

Interactive Server (the classic Blazor Server hosting model) runs components on the server and keeps a SignalR connection, usually over WebSockets, to the browser. UI events travel to the server, the component re-renders there, and only the DOM differences travel back. The server-side state for each connected browser tab is called a circuit; it tolerates brief disconnections and the client tries to reconnect. .NET 10 can persist circuit state so users can resume after a longer disconnect, and .NET 11 lets the server request a graceful circuit pause before deployments.

Benefits: a small download and fast first load, full .NET API compatibility, direct access to databases and internal services, and app code that never leaves the server. Costs: every interaction pays a network round trip, there is no offline support, and server memory and connections grow with the number of open tabs, so scaling out needs sticky sessions or the Azure SignalR Service.

Pitfalls:

  • High-latency users. Typing with @bind:event="oninput" sends a message per keystroke; debounce or keep that interaction static or on WebAssembly.
  • Per-tab memory. Large data cached in component fields multiplies by open tabs; page data and keep circuits lean.
  • Load balancers without session affinity break circuits; configure affinity or use Azure SignalR Service.

Interactive WebAssembly runs components in the browser on a WebAssembly build of the .NET runtime. The runtime, the app’s assemblies and dependencies are downloaded once (trimmed, compressed and cached by the browser), and afterwards UI events are handled locally on the browser’s UI thread with no server round trip. Components must live in the .Client project so they are compiled for the browser, and they reach data through HTTP APIs, because there is no direct database access from the client. A standalone Blazor WebAssembly app has no server rendering at all and can be hosted as static files on a CDN, and built as a Progressive Web App to work offline.

Ahead-of-time (AOT) compilation to WebAssembly improves runtime speed at the cost of a larger download; the default interpreter with partial JIT support is smaller. The main trade-offs are the first-visit download size, a subset of .NET APIs available in the browser sandbox, and the fact that code and data sent to the client can be inspected.

Pitfalls:

  • Secrets in the client. Connection strings, API keys and business rules shipped to WebAssembly are visible to users; keep them behind a server API.
  • Large first download. Trim dependencies, lazy-load assemblies for rarely used areas, and measure the published payload.
  • Prerendered state lost on start. Data loaded during prerendering is loaded again in the browser unless you persist it with [PersistentState].

Interactive Auto combines the two interactive modes. On a user’s first visit the component runs as Interactive Server, so it is interactive quickly without waiting for a download, while the WebAssembly runtime downloads in the background. On later visits, once the bundle is cached, the component runs on WebAssembly and no longer uses a circuit. Because the same component may run in either place, it must be written for both: it lives in the .Client project, gets data through an abstraction (for example an IOrderService with a server implementation that queries the database and a client implementation that calls an HTTP API), and must not assume server-only APIs.

Auto is a good default for interactive features that should feel instant on first load but scale like client-side code for returning users.

Pitfalls:

  • Two data paths to maintain. Server and client implementations of a service can drift; share the interface and test both.
  • Data exposure. Persisted prerendered state in Auto mode may reach the browser, as in WebAssembly; never include sensitive data.
  • Debugging the wrong host. Use RendererInfo.Name to confirm whether a component is running on Server or WebAssembly.

Blazor Hybrid hosts Razor components inside a native app built with .NET MAUI, WPF or Windows Forms. Components run directly in the app’s .NET process, not on WebAssembly, and render HTML and CSS into an embedded web view (BlazorWebView) through a local channel. They have full access to native device APIs through normal .NET code and can share a Razor class library with a Blazor Web App, so one set of components serves web, desktop and mobile.

The costs are those of any native app: separate builds, packaging and store or installer deployment per platform, and users must install the app.

Pitfalls:

  • Assuming web hosting features. Static SSR, render modes and enhanced navigation do not apply; Hybrid apps render interactively in the web view.
  • Platform-specific code in shared components. Put device access behind interfaces so shared components still run on the web.
Requirement Static SSR Interactive Server Interactive WebAssembly Interactive Auto Hybrid
Fast first load, small payload Best Good Slower first visit Good Installed app
Rich interactivity Limited Yes Yes Yes Yes
Works offline No No Standalone PWA No Yes
Direct database and server access Yes Yes Through APIs Through APIs on WebAssembly Through APIs
Code stays private on the server Yes Yes No Partly No
Server cost grows with active users Per request Per open tab Low Until users switch to WebAssembly None
Static file or CDN hosting No No Standalone only No No

A practical default for a line-of-business app such as OrdersPortal: static SSR for most pages, Interactive Server for internal admin screens used on a fast network, and Interactive Auto or WebAssembly for highly interactive public-facing features.

What is a render mode, and how does it relate to the older hosting models? A render mode decides where a component renders and whether it is interactive: Static Server, Interactive Server, Interactive WebAssembly or Interactive Auto. The older terms Blazor Server and Blazor WebAssembly described a whole app; since .NET 8 a Blazor Web App mixes them per component.

Why does an interactive component run its initialization twice? Prerendering creates an instance on the server to produce the initial HTML, then a second instance starts when the circuit or WebAssembly runtime becomes interactive. Persist the data with [PersistentState] or disable prerendering for that component.

When would you choose Interactive Server over WebAssembly? When users are on low-latency networks, the app needs direct access to server resources or full .NET APIs, code must stay private, and a small initial payload matters more than server cost, as in internal line-of-business tools.

What breaks when a Blazor Server app is placed behind a load balancer? Circuits live in one server’s memory, so requests from the same tab must reach the same server. Without session affinity or Azure SignalR Service, users see reconnection failures.

Senior scenario: a public order-tracking site built as Interactive Server struggles at 20,000 concurrent visitors. How would you redesign it? Most of the site only displays data, so make those pages static SSR with streaming rendering and caching (CacheView in .NET 11, output caching or a CDN for anonymous content), which removes the circuits entirely. Keep interactivity only for components that need it and give them Interactive Auto or WebAssembly so returning users run them in the browser. Expose the needed data through cached HTTP APIs, and load-test before and after with realistic connection counts.