Component Tag Helper in ASP.NET Core

By Daniel Roth and Luke Latham

To render a component from a page or view, use the Component Tag Helper.

Prerequisites

Follow the guidance in the Prepare the app to use components in pages and views section of the Integrate ASP.NET Core Razor components into Razor Pages and MVC apps article.

Component Tag Helper

The following Component Tag Helper renders the Counter component in a page or view:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Pages

...

<component type="typeof(Counter)" render-mode="ServerPrerendered" />

The preceding example assumes that the Counter component is in the app's Pages folder. The placeholder {APP ASSEMBLY} is the app's assembly name (for example, @using BlazorSample.Pages).

The Component Tag Helper can also pass parameters to components. Consider the following ColorfulCheckbox component that sets the check box label's color and size:

<label style="font-size:@(Size)px;color:@Color">
    <input @bind="Value"
           id="survey" 
           name="blazor" 
           type="checkbox" />
    Enjoying Blazor?
</label>

@code {
    [Parameter]
    public bool Value { get; set; }

    [Parameter]
    public int Size { get; set; } = 8;

    [Parameter]
    public string Color { get; set; }

    protected override void OnInitialized()
    {
        Size += 10;
    }
}

The Size (int) and Color (string) component parameters can be set by the Component Tag Helper:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Shared

...

<component type="typeof(ColorfulCheckbox)" render-mode="ServerPrerendered" 
    param-Size="14" param-Color="@("blue")" />

The preceding example assumes that the ColorfulCheckbox component is in the app's Shared folder. The placeholder {APP ASSEMBLY} is the app's assembly name (for example, @using BlazorSample.Shared).

The following HTML is rendered in the page or view:

<label style="font-size:24px;color:blue">
    <input id="survey" name="blazor" type="checkbox">
    Enjoying Blazor?
</label>

Passing a quoted string requires an explicit Razor expression, as shown for param-Color in the preceding example. The Razor parsing behavior for a string type value doesn't apply to a param-* attribute because the attribute is an object type.

The parameter type must be JSON serializable, which typically means that the type must have a default constructor and settable properties. For example, you can specify a value for Size and Color in the preceding example because the types of Size and Color are primitive types (int and string), which are supported by the JSON serializer.

In the following example, a class object is passed to the component:

MyClass.cs:

public class MyClass
{
    public MyClass()
    {
    }

    public int MyInt { get; set; } = 999;
    public string MyString { get; set; } = "Initial value";
}

The class must have a public parameterless constructor.

Shared/MyComponent.razor:

<h2>MyComponent</h2>

<p>Int: @MyObject.MyInt</p>
<p>String: @MyObject.MyString</p>

@code
{
    [Parameter]
    public MyClass MyObject { get; set; }
}

Pages/MyPage.cshtml:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}
@using {APP ASSEMBLY}.Shared

...

@{
    var myObject = new MyClass();
    myObject.MyInt = 7;
    myObject.MyString = "Set by MyPage";
}

<component type="typeof(MyComponent)" render-mode="ServerPrerendered" 
    param-MyObject="@myObject" />

The preceding example assumes that the MyComponent component is in the app's Shared folder. The placeholder {APP ASSEMBLY} is the app's assembly name (for example, @using BlazorSample and @using BlazorSample.Shared). MyClass is in the app's namespace.

RenderMode configures whether the component:

  • Is prerendered into the page.
  • Is rendered as static HTML on the page or if it includes the necessary information to bootstrap a Blazor app from the user agent.
Render Mode Description
ServerPrerendered Renders the component into static HTML and includes a marker for a Blazor Server app. When the user-agent starts, this marker is used to bootstrap a Blazor app.
Server Renders a marker for a Blazor Server app. Output from the component isn't included. When the user-agent starts, this marker is used to bootstrap a Blazor app.
Static Renders the component into static HTML.

While pages and views can use components, the converse isn't true. Components can't use view- and page-specific features, such as partial views and sections. To use logic from a partial view in a component, factor out the partial view logic into a component.

Rendering server components from a static HTML page isn't supported.

Additional resources