Edit

Control <head> content in ASP.NET Core Blazor apps

  • Article

Note

This isn't the latest version of this article. To switch to the latest, use the ASP.NET Core version selector at the top of the table of contents.

Version selector

If the selector isn't visible in a narrow browser window, widen the window or select the vertical ellipsis (⋮) > Table of contents.

Table of contents selector

Razor components can modify the HTML <head> element content of a page, including setting the page's title (<title> element) and modifying metadata (<meta> elements).

Control <head> content in a Razor component

Specify the page's title with the PageTitle component, which enables rendering an HTML <title> element to a HeadOutlet component.

Specify <head> element content with the HeadContent component, which provides content to a HeadOutlet component.

The following example sets the page's title and description using Razor.

Pages/ControlHeadContent.razor:

@page "/control-head-content"

<h1>Control <head> content</h1>

<p>
    Title: @title
</p>

<p>
    Description: @description
</p>

<PageTitle>@title</PageTitle>

<HeadContent>
    <meta name="description" content="@description">
</HeadContent>

@code {
    private string description = "Description set by component";
    private string title = "Title set by component";
}

@page "/control-head-content"

<h1>Control <head> content</h1>

<p>
    Title: @title
</p>

<p>
    Description: @description
</p>

<PageTitle>@title</PageTitle>

<HeadContent>
    <meta name="description" content="@description">
</HeadContent>

@code {
    private string description = "Description set by component";
    private string title = "Title set by component";
}

Control <head> content during prerendering

This section applies to prerendered Blazor WebAssembly apps and Blazor Server apps.

When Razor components are prerendered, the use of a layout page (_Layout.cshtml) is required to control <head> content with the PageTitle and HeadContent components. The reason for this requirement is that components that control <head> content must be rendered before the layout with the HeadOutlet component. This order of rendering is required to control head content.

If the shared _Layout.cshtml file doesn't have a Component Tag Helper for a HeadOutlet component, add it to the <head> elements.

In a required, shared _Layout.cshtml file of a Blazor Server app or Razor Pages/MVC app that embeds components into pages or views:

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

In a required, shared _Layout.cshtml file of a prerendered hosted Blazor WebAssembly app:

<component type="typeof(HeadOutlet)" render-mode="WebAssemblyPrerendered" />

HeadOutlet component

The HeadOutlet component renders content provided by PageTitle and HeadContent components.

In an app created from the Blazor WebAssembly project template, the HeadOutlet component is added to the RootComponents collection of the WebAssemblyHostBuilder in Program.cs:

builder.RootComponents.Add<HeadOutlet>("head::after");

When the ::after pseudo-selector is specified, the contents of the root component are appended to the existing head contents instead of replacing the content. This allows the app to retain static head content in wwwroot/index.html without having to repeat the content in the app's Razor components.

In Blazor Server apps created from the Blazor Server project template, a Component Tag Helper renders <head> content for the HeadOutlet component in Pages/_Host.cshtml:

In Blazor Server apps created from the Blazor Server project template, a Component Tag Helper renders <head> content for the HeadOutlet component in Pages/_Layout.cshtml:

<head>
    ...
    <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />
</head>

Not found page title

In Blazor apps created from Blazor project templates, the NotFound component template in the App component (App.razor) sets the page title to Not found.

App.razor:

<PageTitle>Not found</PageTitle>

Additional resources

Mozilla MDN Web Docs documentation: