Blazor tutorial for beginners in 2027 (Step-by-step)

Blazor is a modern front-end web framework powered by HTML, CSS, and C#. It empowers developers to build rich, interactive web applications significantly faster by unifying the technology stack. I remember the nightmare of juggling separate JavaScript frameworks and C# back-ends on older projects, constantly translating data between them. Blazor completely eliminates that friction. In this post, I will break down what Blazor is, explore its project architecture, explain component logic, dive into event handling and data binding, cover the different render modes, and walk through a complete CRUD operation setup.

Table of Contents

What is Blazor?

Blazor is a modern front-end web framework that is a core part of the .NET platform. It allows you to build your entire application—from front-end to back-end—using a single development stack, sharing the exact same logic between the client and the server.

Component-based architecture

The backbone of Blazor is its component-based architecture. A Blazor component is a reusable piece of web UI that encapsulates both the rendering and the interface event handling logic.

You can build your own custom components from scratch.
Blazor also provides a massive library of built-in components for common use cases.
Components can be rendered directly from the server or entirely on the client.
Depending on the specific interactivity required, you can mix and match—rendering different components, or even entire pages within the same app, from the server, the client, or a combination of both.

Blazor is not just trapped in the browser. With a feature called Blazor Hybrid, you can blend native and web technologies to build highly performant native mobile and desktop applications.

How to create your first Blazor Web App?

When firing up a new project in Visual Studio, select the Blazor Web App template. You can stick with the default settings:

Leave the project name and location as default.
Make sure it is targeting .NET 8.
The Interactive render mode should default to Server.
Leave the Interactivity location set to Per page/component.

When you run the project (using Start without debugging), you will see three default pages:

Home: The main page displaying a simple “Hello, world!” message.
Counter: A basic counter that increments when you click a button.
Weather: A page that loads some dummy weather data.

You can navigate between these using the sidebar menu.

Project structure: what does each file do?

Project file (.csproj)

Every C#-based .NET project has a .csproj file. This is the master configuration file that dictates exactly how the project is built and compiled. I once accidentally deleted a line in here and broke my entire build, so be careful when editing it manually.

It specifies the exact .NET version used.
It enables nullable reference types.
It enables implicit usings. This feature automatically injects common namespace imports based on the project type, saving you from typing the same using directives at the top of every single file.

Program.cs

Program.cs is the absolute entry point of the application. The flow works like this:

A static CreateBuilder method is called to generate a new WebApplicationBuilder instance.
Services for the application are configured here. This is where Razor components and interactive server components are injected.
The application is Built.
Middleware is defined:
- Middleware that redirects HTTP requests securely to HTTPS.
- Middleware that serves static files (HTML, CSS, JavaScript) straight from the wwwroot directory.
- Middleware that provides robust protection against cross-site request forgery attacks.
The App component is mapped as the absolute root component for Razor components, with interactive server rendering enabled.
The application boots up and starts listening for HTTP requests.

wwwroot folder

This folder holds all the static web assets served directly to the client’s browser. Your HTML, CSS, and JavaScript files, alongside images and other static assets, live strictly in here.

Properties folder and configuration files

launchSettings.json: Contains the specific settings for how the application launches during development. You can tweak this depending on different development environments.
appsettings.json: Holds the configuration settings the application relies on at runtime. This is where you dump connection strings, logging levels, default parameters, and third-party service configs.
appsettings.Development.json: Holds settings exclusive to your local development environment. You can spin up separate files for staging and production environments using the exact same logic.

Components folder

Every single component of your application lives inside this folder.

App.razor: The absolute root component. It contains the root HTML document, the Blazor router, and the necessary Blazor script tags.
Routes.razor: Defines the routing configuration for the entire app. It maps incoming URLs directly to the specific components or pages that need to be rendered.
Pages folder: Holds all the individual pages, like Home, Counter, and Weather.
Layout folder: Contains the layout components that dictate the overarching structure and visual appearance of the application pages.
- MainLayout.razor: The master layout component. It defines the global structure, like the header, navigation, and footer.
- NavMenu.razor: Contains the raw markup and code for the navigation menu.
_Imports.razor: A special Razor file. It globally imports namespaces used across all Blazor components in the project. This stops you from having to declare the same namespaces inside every single component file.

What are Razor components?

Razor files are a hybrid of HTML and C#. Razor is a specific markup syntax that allows you to embed rendering logic—like if statements and loops—directly alongside your standard HTML markup.

Page directives

The pages sitting inside the Pages folder are just Razor files. For example, the home page is defined by the Home.razor file, which is the Home component.

The @page directive explicitly defines the route for the page. When a user hits the root of the application, the Home component renders.
The PageTitle component sets the text that appears in the browser tab.
The rest of the file is just standard HTML defining the content.

Counter component

The Counter component sits in the Pages folder and renders a simple counter that increments every time you click a button.

The @page directive sets the route.
The render mode directive activates interactive server rendering, which makes user interaction possible.
When the button is clicked, an onclick event fires, triggering the IncrementCount method defined in the code block below.
This method increments the currentCount field, which is also defined in the code block.
The updated value is displayed directly inside a paragraph element using the @ symbol to execute the C# syntax inline.

How to use components?

To drop a component into another part of the application, you just write an HTML-style tag. For example, to stick the Counter component onto the home page, just drop a <Counter/> element directly into the Home.razor file.

How do component parameters work?

Parameters allow you to pass data into a component when you use it. To define a parameter, you add a public C# property to the component and slap the [Parameter] attribute on it. You then pass the value using an HTML attribute that exactly matches the property name.

For example, you can add a parameter to the Counter component following these exact steps:

Inside the code block, define a public int IncrementAmount property with a starting value of 1.
Modify the IncrementCount method so that it increases currentCount by the IncrementAmount instead of just 1.
Inside Home.razor, add the IncrementAmount="10" attribute to the Counter element.

As a result, the counter on the home page will jump by 10 with every click, while the counter on the dedicated Counter page will continue to increment by the default value of 1. This happens because the two counters are entirely independent instances.

How does event handling work?

Web UI elements trigger different types of events in response to user interactions. In Blazor, event handlers are wired up to HTML elements or Blazor components via special attributes. The most common event types are:

Click events
Mouse events
Keyboard events
Form events
Focus events

Click events

In the Counter component, the onclick event is bound to the button using the @onclick attribute. The value it takes is the exact name of the method to call when the event fires. The method itself is defined down in the code block.

Another way to handle events is by utilizing a lambda expression. For example, you can write currentCount++ directly inside the attribute value. I usually stick to methods for complex logic, but if the operation is incredibly simple or short, a lambda expression works perfectly.

Form events (oninput)

The oninput event fires the exact second data is entered into an input field.

Add an input element with type="text".
Add the @oninput="HandleInput" attribute.
Hover over the method name, click the lightbulb icon, and automatically generate a synchronous or asynchronous event handler.
The generated method takes a ChangeEventArgs parameter, which carries extra data about the event. You don’t have to use this parameter if you don’t need it.
Define a variable named text with an empty string as its starting value, and display it inside a paragraph using @text.
Inside the method, write text = (string)e.Value!; to grab the value entered into the input and assign it to the variable.

Since e.Value is an object, it must be explicitly cast to a string. The exclamation mark at the end strictly tells the compiler that the expression will absolutely not be null. As a result, whatever you type into the input instantly mirrors in the paragraph below it.

Mouse events

A classic example of a mouse event is onmouseover. You can create a div element with a solid 1-pixel black border and attach the @onmouseover="HandleMouseOver" attribute to it. Every event type carries a different argument (in this case, a mouse event argument) packed with specific data. If you assign a value like “Hovering over the Div” to a text variable inside the method, that exact text will display the second your mouse crosses into the div.

Keyboard events

Among various keyboard events, onkeydown fires the exact moment a key is pressed down. The Key property of the event argument outputs the specific value of the pressed key. If you assign this value to a text variable, the last key pressed will display on the screen. It detects not just letters and numbers, but almost every other key on the keyboard.

Focus events

onfocus: Fires when a form element is clicked and becomes active.
onblur: Fires when you click entirely outside of the active form element.

For example, you can display text like “You are typing” for onfocus, and “You are not typing, you clicked away” for onblur. Keep in mind that onblur requires you to physically click outside the input, not just hover away from it.

What is data binding?

Data binding physically links the application’s interface directly to the underlying data sources. By keeping the state of the components perfectly synchronized with data changes, it delivers a highly responsive and dynamic user experience.

One-way vs Two-way data binding

One-way data binding: Data flows in one single direction, usually pushing data strictly to the UI for display. Data sitting in C# code or a database is rendered on the interface, usually utilizing the @ symbol.
Two-way data binding: Data flows simultaneously in both directions. When a value changes in the UI, the C# code instantly updates. When a change happens in the C# code, the UI instantly reflects it.

The @bind attribute

Instead of manually writing out an event handler, you can bind an input directly to a field using the @bind attribute. For example, typing <input @bind="text" /> achieves the exact same result as the previous event handler but in a single line of code. The content of the input is bound directly to the text field, and the value of that field is displayed below.

Changing the binding event

By default, binding triggers on the onchange event, meaning it only updates when you click entirely out of the input box. To change this behavior, use @bind:event="oninput". When you do this, the value updates instantly with every single keystroke.

Executing code with @bind:after

If you need to execute a specific block of code immediately after a binding occurs, use the @bind:after attribute. This is incredibly useful in scenarios where you want to trigger a database query the moment text is dropped into a search box.

Example flow:

Specify a method using @bind:after="Search".
Create an asynchronous method named async Task Search().
Define a field named result with an empty string as its starting value, and display it inside a paragraph using @result.
Inside the method, simulate a 3-second wait using await Task.Delay(3000), and then hardcode the result value to “150 results were found”.

Exactly 3 seconds after you finish typing, the search method executes and the result populates the paragraph.

What are the different render modes?

Blazor features four primary render modes. We can explore these by digging into the default Blazor Web App project.

Static Server-Side Rendering

By default, Blazor components are rendered statically straight from the server. The second a request hits a component, the server fires back raw HTML as the response, and the job is done. Absolutely no state is maintained on the server.

Static components are perfect for scenarios where you just need to render flat HTML and do not need to process any interactive UI events from the user. In the default application, the Home and Weather pages, along with the layout component, are rendered completely statically.

Enhanced navigation and form handling: Blazor can actually make static components feel much more responsive to user interactions.

Enhanced navigation allows users to seamlessly jump between pages while preserving the application state, completely bypassing the need for a full page refresh. Blazor intercepts the navigation, fires a fetch request to the server, grabs the returning HTML, and surgically applies only the necessary changes to the DOM. I love this feature because it makes the app feel lightning-fast.
Navigation is enhanced by default. Forms, however, can be enhanced optionally.

Streaming Rendering

Streaming rendering allows chunks of a page or component to render the second the data is ready on the server. This is incredibly useful when the page has to execute long-running asynchronous tasks—like firing a fetch request to an API or pulling massive amounts of data from a database—before it can fully render.

Instead of waiting for the entire page to finish processing, the server starts streaming the HTML content directly to the client as soon as it is ready. You will typically see placeholder content like “Loading…”. This allows users to start interacting with the page before the heavy content fully loads. Once the asynchronous tasks wrap up, the rest of the content renders smoothly.

Streaming rendering on the Weather page:

The page is locked into this mode using the [StreamRendering] attribute.
An if block sits inside the markup. If the weather data is missing, it displays the “Loading…” paragraph; if it is there, it renders the data table.
The OnInitializedAsync method in the code block is called the second the component initializes asynchronously. It uses Task.Delay to simulate an asynchronous call rather than hitting a real API.
Once the data is generated, the component re-renders, and the update is pushed to the client.

When you refresh the page, you will see the “Loading…” text first, followed by the data table popping in about half a second later.

Interactive Render Modes

To build fully interactive Blazor components, you rely on two core interactive render modes:

Interactive Server Rendering: UI events are processed directly on the server over an active WebSocket connection established with the browser. Blazor shoots the events over this connection to the server, and then updates the browser’s DOM with the rendered changes. The downside here is that requiring the server to maintain a constantly open connection with the browser can drive up server costs or introduce heavy latency on weak networks.
Interactive WebAssembly Rendering: The raw component code is downloaded straight to the browser and executed entirely on the client side using a WebAssembly-based .NET runtime. Because the .NET runtime has to be downloaded, the initial load time is noticeably longer. However, once the download finishes, the runtime caches itself, becomes instantly available for future use, and completely shifts the entire workload from the server to the client.
Interactive Auto Render Mode: This third mode combines the absolute best of both approaches. Components are initially rendered from the server, while the .NET WebAssembly runtime downloads silently in the background. Once the download wraps up, the component automatically switches over to WebAssembly-based rendering for all subsequent visits. Because the page renders from the server initially, it loads incredibly fast, and then the workload is fully offloaded to the client, completely severing the need for an active server connection.

Interactive Server Rendering in practice

In the default Blazor project, the Counter is the only component utilizing the interactive server mode. At the very top of the page, the render mode directive explicitly sets the interactivity to InteractiveServer. When you click the button, the counter increments—proving the page is highly interactive.

Right-click in your browser, hit Inspect to open developer tools, switch to the Network tab, and refresh the page. You will spot a WebSocket connection sitting in a pending state. This proves there is an actively open WebSocket connection with the server. If you jump to another page, it logs exactly how long that connection stayed open. When you jump back to the Counter, a brand new WebSocket connection spins up. This proves that components using interactive server rendering open a connection when active and kill it when not in use.

Interactive Auto and WebAssembly Modes

Since the default project doesn’t support the other two render modes out of the box, we have to spin up a new project. In a new Blazor Web App project, the interactivity type options are:

None: Static server-side rendering, absolutely zero interactivity.
Server: Interactive server rendering.
WebAssembly: Interactive WebAssembly rendering.
Auto: Interactive auto rendering.

You get two options for interactivity location:

Per page/component: You manually define the interactivity for each individual page or component.
Global: Every single component in the application is locked into the exact same interactivity setting.

When you select Interactive Auto, the solution splits into two distinct projects:

Server project: Holds all the heavy server code and structure, looking very similar to previous Blazor Web projects. Inside Program.cs, both interactive server and interactive WebAssembly rendering are fully enabled.
Client project: Compiles the code that will be physically downloaded to the browser and executed client-side on the user’s machine.

In the Server project’s Pages folder, all pages and components—except the Counter—remain exactly the same. The Counter, being the only interactive component, has been migrated to the client project. Any page or component you want running directly from the browser must be dumped into the client project. In the Counter, the render mode directive is locked to InteractiveAuto.

How Auto mode operates: While sitting on the home page, open the Network tab in developer tools and click over to the Counter page. You will see a massive dump of libraries downloading. During this, the page is fully interactive and the Counter works flawlessly. If you filter by WebSockets, you will see the server connection is actively open. If you filter by WebAssembly, you will see the client code libraries actively downloading. The most critical file here is dotnet.native.wasm—this is the actual .NET WebAssembly runtime downloading silently in the background.

Once the download completely finishes, navigate back to the home page and then click the Counter again. The page is still perfectly interactive, but a new WebSocket connection does not open. The rendering has successfully migrated from interactive server to interactive WebAssembly. Every single UI event triggered by the user is now being processed entirely on the browser side.

Interactive WebAssembly mode: If you change the interactivity on the Counter page to InteractiveWebAssembly, clear your storage data, and hit the page, the component will not be interactive immediately. Because this mode requires a longer initial load time, the libraries and the .NET WebAssembly runtime must fully download in the background before the component becomes interactive. This is the primary drawback of WebAssembly mode. However, once everything is downloaded and the runtime is safely cached, user events process significantly faster directly on the client’s browser. Since this mode completely bypasses the server, absolutely no WebSocket connection is ever created.

How to execute CRUD operations?

Before you can build an application of any real complexity, you must learn how to handle CRUD operations. CRUD stands for Create, Read, Update, and Delete—these are the absolute foundational operations of all applications. In this section, we will use scaffolding to instantly generate the components that handle these operations. I used to write all my CRUD views by hand, and learning scaffolding saved me literally days of tedious typing.

Creating the Project and Model

Spin up a new project named BlazorCRUD using the Blazor Web App template.
Set the Interactivity type to Server, and the interactivity location to Per page/component.
Add a Models folder directly into the project directory and create a Student model class inside it.

The Student class should contain these exact properties:

Id (int)
Name (nullable string)
Age (int)
Birthday (DateTime)

Creating Pages with Scaffolding

Blazor can automatically generate every single page and component needed to execute CRUD operations for a model.

Right-click the Components/Pages folder and select Add > New Scaffolded Item.
Under Razor Components, select Razor Components using Entity Framework (CRUD).
Select the Student class as your specific Model.
Add a brand new DbContext class (since one hasn’t been built yet). The DbContext is the crucial C# class that wires your models directly to the database. Every time you introduce a new data model, you inject an instance of it straight into this context class. Whenever you need to pull specific data, you route it through this context.
Leave the database provider as SQL Server and hit Add.

Blazor does all the heavy lifting for you. A folder named Student spawns inside the Pages folder, housing five distinct components: Create, Delete, Details, Edit, and Index. If you want, you can choose to generate only a few of them.

Preparing the Database

Create a brand new SQL Server database via View > Server Explorer.
Enter the exact server name pulled from SQL Server Management Studio.
To avoid logging in with a password every single time, set the Encrypt field to Optional/False and check the Trust Server Certificate option.
Give the database a clear name (for example, BlazorCRUDData).
Grab the connection string from the Properties section of the database instance and paste it directly into the appsettings.json file. During scaffolding, Blazor injected a default dummy connection string here; you just need to overwrite it with your actual database value.
The connection string is already configured as a service inside the Program.cs file.

Running Migrations

To dictate the exact database schema, you need to add a migration:

Navigate to Tools > NuGet Package Manager > Package Manager Console.
Run the Add-Migration command followed by a descriptive migration name. A Migrations folder will spawn in your project, containing a C# class defining the exact database schema.
Run the Update-Database command. Your model is instantly committed to the database with the exact properties you specified.

Testing CRUD Operations

The route for the Index page is /students. Initially, you will see a completely empty table.

Navigate to the creation page using Create New and punch in some student details. Hit Create, and the student commits to the database and populates the table.
The three links in the final column route you directly to the Details, Edit, and Delete pages.
If you tweak something on the Edit page and hit Save, the update commits instantly.
You can wipe the student entirely from the database on the Delete page.

Index Page and QuickGrid

The core piece of the Index page is the QuickGrid, a heavy-duty data grid component built right into Blazor. QuickGrid can pull data from massive sources and offers robust features like sorting and pagination out of the box.

In the Items attribute, data is pulled straight through the DbContext. The context is injected at the top of the page using @inject and assigned the name DB.
Every PropertyColumn tag explicitly defines a column in the table. The Property attribute specifies the exact property from the Student model.
The final column utilizes the built-in TemplateColumn component. This uses the student ID to build direct links to the Edit, Details, and Delete pages.

Customization examples:

To strip out the raw time data from the birthdate, you can append a format attribute like Format="MM/dd/yyyy".
To clean up the column header, use Title="Date of Birth".

Create Page and EditForm

On the Create page, the standard HTML form tag is completely replaced by the built-in EditForm component. This component makes binding raw form data directly to a model incredibly simple.

Method="post" defines the exact method type.
The Model attribute specifies the data model (Student). The data pushed from the form binds directly to this Student property.
The [SupplyParameterFromForm] attribute placed on the property ensures the data binds to this specific property the exact second the form is submitted.
The OnValidSubmit attribute is locked to the AddStudent method. When the form data is fully validated and submitted correctly, this method executes. The method uses Add to push the student into the context, commits the changes to the database, and redirects the user right back to the index page.
The FormName attribute is mandatory when you have multiple forms sitting on the same page; it tells the system exactly which form data binds to which property. If you only have one form, you can skip it.
The Enhance attribute activates enhanced form handling. When the form submits, Blazor intercepts the request, fires a fetch request to the server, grabs the response, and surgically alters the DOM.

Inside the form, every div houses a label and an input component:

InputText: Accepts raw text input and binds directly to the Student.Name property via @bind-Value.
InputNumber: Used specifically for numeric data.
InputDate: Used specifically for date data.
A ValidationMessage component sits at the end of every single div.
The DataAnnotationsValidator and ValidationSummary components are placed at the very top of the page.

Validation

You can enforce strict constraints on properties by slapping data annotations onto the Student model:

[Required] for the Name
[Range(18, 35)] for the Age

Because of this, the DataAnnotationsValidator triggers error messages at the end of every input and piles them into the ValidationSummary at the top of the page. For instance, if you type in the age 36, the form utterly refuses to submit, throwing the error: “The field Age must be between 18 and 35”. Once you correct the value and resubmit, the student commits to the database perfectly. I highly recommend relying on these built-in validators rather than trying to write your own custom validation scripts.

Instant validation: If you want validation to trigger the absolute second you click out of an input, you must make the page interactive. To pull this off, specify the render mode at the top of the page as InteractiveServer. Because the application was built to allow interactive server rendering, this works flawlessly. Now, if you punch in a bad value and click away, the error fires instantly. Validated fields highlight with a clean green border.

Delete Page

At the top of the page, a massive header asks if you genuinely want to delete the student. If the student hasn’t loaded yet, it shows a standby message. Once loaded, it dumps all the student’s data and displays an EditForm specifically for the deletion process.

The Id property utilizes the [SupplyParameterFromQuery] attribute. This elegantly pulls the ID value straight out of the URL.
The OnInitializedAsync method fires the second the component renders, hunting down the student with that exact ID in the database.
The student’s name, age, and birthdate render on screen, and that exact same data is leveraged inside the EditForm.
Clicking the button triggers the DeleteStudent method. This method rips the student entirely out of the context, commits the deletion to the database, and punts you back to the index page.

Details Page

On the Details page, the Id property also yanks its value straight from the URL. When the component renders, the OnInitializedAsync method fires, hunts down the student with that specific ID in the database, and displays the raw data to the user.

Edit Page

The Edit page acts almost identically to the Create page, leveraging the exact same built-in EditForm component. The only difference is that when the component renders, it hunts down the student using the ID from the URL, so the inputs are fully pre-populated. You can tweak any input you want.

When you hit the Save button, the UpdateStudent method fires:

The very first line forces the entity’s state to Modified so the context actually tracks the changes.
The changes are committed to the database.
If an error triggers, the user is punted to a not found page; otherwise, they are redirected right back to the main students page.

Conclusion

By now, you should have a solid grasp on what Blazor is, how its project architecture functions, and how to effectively use components, parameters, event handling, and data binding. You also understand the mechanics behind the four primary render modes and how to execute a complete CRUD application using scaffolding. Once you nail these fundamentals, the best way to solidify your knowledge is to build a simple application from scratch, like a basic food menu web app.