How to Implement Blazor Web App Render Modes

A render mode tells a Blazor Web App where a component runs and whether it is interactive. Since .NET 8 there are four options: static server-side rendering (the default, no interactivity), Interactive Server, Interactive WebAssembly and Interactive Auto. You enable the interactive modes in Program.cs, then apply one with the @rendermode directive on a component, on a component instance, or globally on the Routes component in App.razor.

This is the setup I use in our Blazor classes. An earlier version of this post had code snippets that don't compile, so I've rewritten it with the API as it actually exists in .NET 8 and later. Check Microsoft's "ASP.NET Core Blazor render modes" documentation for the version you target.

What are the four Blazor render modes?

• Static server-side rendering (static SSR): the server renders HTML and sends it. No event handlers run after that. It's the default when no render mode is set, and ideal for content pages and SEO.
• Interactive Server: the component runs on the server and the browser talks to it over a SignalR connection. Fast first load, but each interaction needs a round trip.
• Interactive WebAssembly: the component runs in the browser on the .NET WebAssembly runtime. Slower first load, then local interactions with no server connection.
• Interactive Auto: uses Interactive Server while the WebAssembly runtime downloads in the background. On later visits, once the runtime is cached, the component runs on WebAssembly.

For the bigger trade-offs between server and client, see Blazor WebAssembly vs Server.

How do you enable render modes in Program.cs?

Register the interactive render modes you plan to use, then map them on the endpoint. The Blazor Web App template does this for you when you choose an interactivity option.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();

var app = builder.Build();

app.UseStaticFiles();
app.UseAntiforgery();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof(MyApp.Client._Imports).Assembly);

app.Run();

Using only Interactive Server? Leave out the WebAssembly calls. Components that run on WebAssembly or Auto must live in the separate .Client project, because that's the assembly the browser downloads.

How do you apply a render mode to a component?

The template's _Imports.razor includes @using static Microsoft.AspNetCore.Components.Web.RenderMode, which lets you write the short names.

On the component definition:

@page "/counter"
@rendermode InteractiveServer

<p>Current count: @currentCount</p>
<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;
    private void IncrementCount() => currentCount++;
}

Or on a specific instance, from a parent component:

<Counter @rendermode="InteractiveWebAssembly" />

For static SSR, set no render mode at all.

How do you set one render mode for the whole app?

Apply it to Routes and HeadOutlet in App.razor:

<HeadOutlet @rendermode="InteractiveAuto" />
...
<Routes @rendermode="InteractiveAuto" />

Global interactivity is simpler to reason about. Per-page interactivity gives you static, SEO-friendly pages by default and interactivity only where it's needed.

How do you control prerendering and streaming?

Interactive components are prerendered on the server by default, so users see HTML immediately. To turn that off for a component (for example, one that relies on browser-only APIs):

@rendermode @(new InteractiveServerRenderMode(prerender: false))

For static SSR pages that load slow data, streaming rendering sends the page shell first and fills in content as it arrives:

@attribute [StreamRendering]

When should you use each render mode?

• Static SSR: marketing pages, blog posts, documentation, anything that must be fast and indexable.
• Interactive Server: internal dashboards and admin screens on a reliable network, or components that need direct server resources.
• Interactive WebAssembly: offline-capable features, heavy client-side work, or public apps where you don't want a server circuit per user.
• Interactive Auto: public apps where you want a fast first visit and client-side execution afterwards.

What are the common pitfalls?

• Missing registration. Using @rendermode InteractiveWebAssembly without AddInteractiveWebAssemblyComponents() and the matching endpoint call throws at runtime.
• Wrong project. WebAssembly and Auto components placed in the server project can't be downloaded by the browser.
• Mixing modes in a tree. A child can't switch to a different interactive mode from its interactive parent. Plan boundaries at page or section level.
• Server-only services in Auto components. Code that runs in both places must use services available in both, typically an interface with an HTTP-based implementation on the client.
• State during prerendering. Data loaded during prerender is fetched again when the component becomes interactive unless you persist it with PersistentComponentState.

Taking it live? Our Blazor production checklist covers security, performance and hosting. TechNet Consultancy's Blazor training works through all four modes in a real project.

FAQ

What is the default render mode in a Blazor Web App?

Static server-side rendering. Components aren't interactive unless you apply an interactive render mode.

Which .NET version introduced Blazor render modes?

.NET 8, released in November 2023, introduced the Blazor Web App template and the per-component render modes.

Does Interactive Auto switch from Server to WebAssembly while the page is open?

No. A component keeps the mode it started with. Auto uses Server on early visits while the WebAssembly runtime downloads, and WebAssembly on later visits once it's cached.

Can I mix render modes on one page?

Yes, for sibling components, as long as each interactive mode is registered. An interactive parent's children can't use a different interactive mode.

Why doesn't my button click do anything?

The component is probably rendering in static SSR mode. Add an interactive render mode to it, or set one globally in App.razor.