ASP.NET Core Blazor layouts

By Rainer Stropek and Luke Latham

Some app elements, such as menus, copyright messages, and company logos, are usually part of app's overall layout and used by every component in the app. Copying the code of these elements into all of the components of an app isn't an efficient approach—every time one of the elements requires an update, every component must be updated. Such duplication is difficult to maintain and can lead to inconsistent content over time. Layouts solve this problem.

Technically, a layout is just another component. A layout is defined in a Razor template or in C# code and can use data binding, dependency injection, and other component scenarios.

To turn a component into a layout, the component:

  • Inherits from LayoutComponentBase, which defines a Body property for the rendered content inside the layout.
  • Uses the Razor syntax @Body to specify the location in the layout markup where the content is rendered.

The following code sample shows the Razor template of a layout component, MainLayout.razor. The layout inherits LayoutComponentBase and sets the @Body between the navigation bar and the footer:

@inherits LayoutComponentBase

<header>
    <h1>Doctor Who&trade; Episode Database</h1>
</header>

<nav>
    <a href="masterlist">Master Episode List</a>
    <a href="search">Search</a>
    <a href="new">Add Episode</a>
</nav>

@Body

<footer>
    @TrademarkMessage
</footer>

@code {
    public string TrademarkMessage { get; set; } = 
        "Doctor Who is a registered trademark of the BBC. " +
        "https://www.doctorwho.tv/";
}

In an app based on one of the Blazor app templates, the MainLayout component (MainLayout.razor) is in the app's Shared folder.

Default layout

Specify the default app layout in the Router component in the app's App.razor file. The following Router component, which is provided by the default Blazor templates, sets the default layout to the MainLayout component:

<Router AppAssembly="typeof(Startup).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
    </Found>
    <NotFound>
        <p>Sorry, there's nothing at this address.</p>
    </NotFound>
</Router>

To supply a default layout for NotFound content, specify a LayoutView for NotFound content:

<Router AppAssembly="typeof(Startup).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
    </Found>
    <NotFound>
        <LayoutView Layout="typeof(MainLayout)">
            <h1>Page not found</h1>
            <p>Sorry, there's nothing at this address.</p>
        </LayoutView>
    </NotFound>
</Router>

For more information on the Router component, see ASP.NET Core Blazor routing.

Specify a layout in a component

Use the Razor directive @layout to apply a layout to a component. The compiler converts @layout into a LayoutAttribute, which is applied to the component class.

The content of the following MasterList component is inserted into the MasterLayout at the position of @Body:

@layout MasterLayout
@page "/masterlist"

<h1>Master Episode List</h1>

Centralized layout selection

Every folder of an app can optionally contain a template file named _Imports.razor. The compiler includes the directives specified in the imports file in all of the Razor templates in the same folder and recursively in all of its subfolders. Therefore, an _Imports.razor file containing @layout MyCoolLayout ensures that all of the components in a folder use MyCoolLayout. There's no need to repeatedly add @layout MyCoolLayout to all of the .razor files within the folder and subfolders. @using directives are also applied to components in the same way.

The following _Imports.razor file imports:

  • MyCoolLayout.
  • All Razor components in the same folder and any subfolders.
  • The BlazorApp1.Data namespace.
@layout MyCoolLayout
@using Microsoft.AspNetCore.Components
@using BlazorApp1.Data

The _Imports.razor file is similar to the _ViewImports.cshtml file for Razor views and pages but applied specifically to Razor component files.

Nested layouts

Apps can consist of nested layouts. A component can reference a layout which in turn references another layout. For example, nesting layouts are used to create a multi-level menu structure.

The following example shows how to use nested layouts. The EpisodesComponent.razor file is the component to display. The component references the MasterListLayout:

@layout MasterListLayout
@page "/masterlist/episodes"

<h1>Episodes</h1>

The MasterListLayout.razor file provides the MasterListLayout. The layout references another layout, MasterLayout, where it's rendered. EpisodesComponent is rendered where @Body appears:

@layout MasterLayout
@inherits LayoutComponentBase

<nav>
    <!-- Menu structure of master list -->
    ...
</nav>

@Body

Finally, MasterLayout in MasterLayout.razor contains the top-level layout elements, such as the header, main menu, and footer. MasterListLayout with the EpisodesComponent is rendered where @Body appears:

@inherits LayoutComponentBase

<header>...</header>
<nav>...</nav>

@Body

<footer>
    @TrademarkMessage
</footer>

@code {
    public string TrademarkMessage { get; set; } = 
        "Doctor Who is a registered trademark of the BBC. " +
        "https://www.doctorwho.tv/";
}

Additional resources