Razor Pages

Build a UI using Razor Pages in Blazor.

Razor pages

UIs built with Blazor contain a collection of components built with Razor Pages. "Component" is a generic term for a class, page, or any programmable unit in Blazor that contains C#, HTML, and CSS. All Blazor components are files that have a .razor extension.

But there is one distinct difference between pages and components: Pages start with the @page directive that designates them as an entire web page and supplies routing information. Components don't use the @page directive. This is because components with the @page directive are used a complete HTML page, where a component is a block of code that runs inside a page.

There's more on routing later in these tutorials. But for now, the @page directive tells the host how to route page requests to Razor Pages. @page "/" marks a page as the default page (often called Index.razor). A page with a directive of @page "/ToDoList" maps to the physical Pages\ToDoList.razor file and routes HTTP requests to <application-root>/ToDoList.

There are two approaches to adding code to Blazor pages and components. The first approach is using the .razor file itself and placing the code inside a @code block after the HTML code. If you’re wondering if this could make the pages more difficult to read and maintain - yes, that can be the case. This is especially true for large enterprise applications. Doing everything in-page tends to work better for small pages or small apps.

The second approach is to create a corresponding class with the same name and extension of .razor.cs. This creates a partial class that is split across the Blazor component and its corresponding partial class. This makes a better separation between the HTML and C# code, yet allows interaction between them. If your app's UI is complex or detailed then this is a good way to keep the code readable and maintainable.

Razor syntax

Razor syntax is C# code interspersed with HTML that render pages and sends them to the client. Razor is the same C# code that is used in MVC. To use Razor expressions, add the @ symbol to render the output of a variable, property, or return value of a method. For example, to render today’s date, use the following:

<span>Today is @DateTime.Today.ToShortDateString()</span>

Notice that Razor and HTML are mixed together. To render a span with a class attribute that renders the value from a variable named shortdate-style, use the following:

<span class="@shortdate-style">Today is @DateTime.Today.ToShortDateString()</span>

To call a function or method is what you'd expect in C#.

<span class="@class">Today is @GetNicelyFormattedDate()</span>

You can do more than simple Razor expressions or function calls. To create a block of Razor code that contains UI logic, enclose the code in @{}. This code may be mixed with HTML.

    switch (DateTime.Now.Hour)
        case < 12:
            <h3>Good Morning</h3>
        case <= 18 and >= 12:
            <h3>Good Afternoon</h3>
        case >18:
            <h3>Good Evening</h3>

Alternatively, the previous code sample could be rewritten as follows, completely in C# and the call to it embedded in HTML. This is often considered easier to read and works with both models - putting all the code in a single .razor file or a Razor partial class.


@code {
    private string GetTimePeriod(DateTime date)
        switch (date.Hour)
            case < 12:
                return "Good Morning";
            case >= 12 and <= 18:
                return "Good Afternoon";
            case > 18:
                return "Good Evening";

Components can be called using declarative syntax. The following sample calls a component named Message and passes the message to it for display as an attribute of the Message tag.

<Message MessageText="Don't forget to do your 'To Dos'" MessageStyle="important-alert"></Message>

The source of the component is found in Message.razor. It displays the MessageText parameter in a paragraph and styles it using the MessageStyle parameter.

<p MessageStyle=@MessageStyle>@MessageText</p>

@code {
public string? MessageText { get; set; }
public string? MessageStyle { get; set; }

There's more on Blazor components in the next tutorial step.


High quality user interfaces on websites have a standardized look and feel to them, with clear and straightforward navigation. There are Blazor project templates available that have basic references and a changeable theme, though you may choose to build from an empty project. Below are a few folders and files of interest regarding layout:

  • App.razor : This file defines which component should be used for layouts, plus routing information.
  • Shared\MainLayout.razor and Shared\MainLayout.razor.css : This is the layout defined in the template, or you may create a main layout component yourself.
  • Shared\NavMenu.razor and Shared\NavMenu.razor.css : The NavMenu file defines the site's navigation. Same as with the main layout, you can create this from scratch.
  • wwwroot\ : This folder has long been in ASP.NET projects, and is in here too for CSS and those times you need JavaScript.


Razor syntax enables you to create web pages using a mix of C# and HTML, and less JavaScript than you normally would in former versions of ASP.NET. It's flexible so you can choose to put the code inside a single Razor page or split the UI and UI logic into partial classes.

See Also