Get started with Razor Components

By Daniel Roth and Luke Latham

Prerequisites:

To create your first Razor Components project in Visual Studio:

  1. Select File > New Project > Web > ASP.NET Core Web Application.
  2. Make sure .NET Core and ASP.NET Core 3.0 are selected at the top.
  3. Choose the Razor Components template and select OK.
  4. Press F5 to run the app.

Congratulations! You just ran your first Razor Components app!

Razor Components project

Razor Components are authored using Razor syntax but are compiled differently than Razor Pages and MVC views. The .razor file extension is used to specify a Razor Component. Razor Pages and MVC views continue to use the .cshtml file extension.

Note

Razor Components can be authored using the .cshtml file extension as long as those files are identified as Razor Component files using the _RazorComponentInclude MSBuild property. For example, an app created using the Razor Component template specifies that all .cshtml files under the Components folder should be treated as Razor Components:

<_RazorComponentInclude>Components\**\*.cshtml</_RazorComponentInclude>

When the app is run, multiple pages are available from tabs in the sidebar:

  • Home
  • Counter
  • Fetch data

On the Counter page, select the Click me button to increment the counter without a page refresh. Incrementing a counter in a webpage normally requires writing JavaScript, but Razor Components provides a better approach using C#.

WebApplication1/Components/Pages/Counter.razor:

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" onclick="@IncrementCount">Click me</button>

@functions {
    int currentCount = 0;

    void IncrementCount()
    {
        currentCount++;
    }
}

A request for /counter in the browser, as specified by the @page directive at the top, causes the Counter component to render its content. Components render into an in-memory representation of the render tree that can then be used to update the UI in a flexible and efficient way.

Each time the Click me button is selected:

  • The onclick event is fired.
  • The IncrementCount method is called.
  • The currentCount is incremented.
  • The component is rendered again.

The runtime compares the new content to the previous content and only applies the changed content to the Document Object Model (DOM).

Add a component to another component using an HTML-like syntax. Component parameters are specified using attributes or child content. For example, a Counter component can be added to the app's homepage by adding a <Counter /> element to the Index component.

WebApplication1/Components/Pages/Index.razor:

@page "/"

<h1>Hello, world!</h1>

Welcome to your new app.

<Counter />

Run the app. The homepage has its own counter.

To add a parameter to the Counter component, update the component's @functions block:

  • Add a property for IncrementAmount decorated with the [Parameter] attribute.
  • Change the IncrementCount method to use the IncrementAmount when increasing the value of currentCount.

WebApplication1/Components/Pages/Counter.razor:

@functions {
    int currentCount = 0;

    [Parameter] int IncrementAmount { get; set; } = 1;

    void IncrementCount()
    {
        currentCount += IncrementAmount;
    }
}

Specify an IncrementAmount parameter in the Home component's <Counter> element using an attribute.

WebApplication1/Components/Pages/Index.razor:

<Counter IncrementAmount="10" />

Run the app. The homepage has its own counter that increments by ten each time the Click me button is selected.

Next steps

Build your first Razor Components app