|
| 1 | +--- |
| 2 | +title: Component Tag Helper in ASP.NET Core |
| 3 | +author: guardrex |
| 4 | +ms.author: riande |
| 5 | +description: Learn how to use the ASP.NET Core Component Tag Helper to render Razor components in pages and views. |
| 6 | +ms.custom: mvc |
| 7 | +ms.date: 03/18/2020 |
| 8 | +no-loc: [Blazor, SignalR] |
| 9 | +uid: mvc/views/tag-helpers/builtin-th/component-tag-helper |
| 10 | +--- |
| 11 | +# Component Tag Helper in ASP.NET Core |
| 12 | + |
| 13 | +By [Daniel Roth](https://github.com/danroth27) and [Luke Latham](https://github.com/guardrex) |
| 14 | + |
| 15 | +To render a component from a page or view, use the [Component Tag Helper](xref:Microsoft.AspNetCore.Mvc.TagHelpers.ComponentTagHelper). |
| 16 | + |
| 17 | +The following Component Tag Helper renders the `Counter` component in a page or view: |
| 18 | + |
| 19 | +```cshtml |
| 20 | +<component type="typeof(Counter)" render-mode="ServerPrerendered" /> |
| 21 | +``` |
| 22 | + |
| 23 | +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: |
| 24 | + |
| 25 | +```razor |
| 26 | +<label style="font-size:@(Size)px;color:@Color"> |
| 27 | + <input @bind="Value" |
| 28 | + id="survey" |
| 29 | + name="blazor" |
| 30 | + type="checkbox" /> |
| 31 | + Enjoying Blazor? |
| 32 | +</label> |
| 33 | +
|
| 34 | +@code { |
| 35 | + [Parameter] |
| 36 | + public bool Value { get; set; } |
| 37 | +
|
| 38 | + [Parameter] |
| 39 | + public int Size { get; set; } = 8; |
| 40 | +
|
| 41 | + [Parameter] |
| 42 | + public string Color { get; set; } |
| 43 | +
|
| 44 | + protected override void OnInitialized() |
| 45 | + { |
| 46 | + Size += 10; |
| 47 | + } |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +The `Size` (`int`) and `Color` (`string`) [component parameters](xref:blazor/components#component-parameters) can be set by the Component Tag Helper: |
| 52 | + |
| 53 | +```cshtml |
| 54 | +<component type="typeof(ColorfulCheckbox)" render-mode="ServerPrerendered" |
| 55 | + param-Size="14" param-Color="@("blue")" /> |
| 56 | +``` |
| 57 | + |
| 58 | +The following HTML is rendered in the page or view: |
| 59 | + |
| 60 | +```html |
| 61 | +<label style="font-size:24px;color:blue"> |
| 62 | + <input id="survey" name="blazor" type="checkbox"> |
| 63 | + Enjoying Blazor? |
| 64 | +</label> |
| 65 | +``` |
| 66 | + |
| 67 | +Passing a quoted string requires an [explicit Razor expression](xref:mvc/views/razor#explicit-razor-expressions), 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. |
| 68 | + |
| 69 | +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. |
| 70 | + |
| 71 | +<xref:Microsoft.AspNetCore.Mvc.Rendering.RenderMode> configures whether the component: |
| 72 | + |
| 73 | +* Is prerendered into the page. |
| 74 | +* Is rendered as static HTML on the page or if it includes the necessary information to bootstrap a Blazor app from the user agent. |
| 75 | + |
| 76 | +| Render Mode | Description | |
| 77 | +| ----------- | ----------- | |
| 78 | +| <xref:Microsoft.AspNetCore.Mvc.Rendering.RenderMode.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. | |
| 79 | +| <xref:Microsoft.AspNetCore.Mvc.Rendering.RenderMode.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. | |
| 80 | +| <xref:Microsoft.AspNetCore.Mvc.Rendering.RenderMode.Static> | Renders the component into static HTML. | |
| 81 | + |
| 82 | +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. |
| 83 | + |
| 84 | +Rendering server components from a static HTML page isn't supported. |
| 85 | + |
| 86 | +## Additional resources |
| 87 | + |
| 88 | +* <xref:Microsoft.AspNetCore.Mvc.TagHelpers.ComponentTagHelper> |
| 89 | +* <xref:mvc/views/tag-helpers/intro> |
| 90 | +* <xref:blazor/components> |
0 commit comments