Skip to content

Statically-rendered layout components #35344

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
guardrex merged 4 commits into from
May 5, 2025
Merged

Statically-rendered layout components #35344

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
797a9fe
Statically-rendered layout components
guardrex May 5, 2025
8f7a06e
Updates
guardrex May 5, 2025
30e1c94
Updates
guardrex May 5, 2025
c3e1ae2
Updates
guardrex May 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions aspnetcore/blazor/components/built-in-components.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ The following built-in Razor components are provided by the Blazor framework. Fo
* [`InputSelect`](xref:blazor/forms/input-components)
* [`InputText`](xref:blazor/forms/input-components)
* [`InputTextArea`](xref:blazor/forms/input-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#layout-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#create-a-layout-component)
* [`LayoutView`](xref:blazor/components/layouts#apply-a-layout-to-arbitrary-content-layoutview-component)
* [`NavigationLock`](xref:blazor/fundamentals/routing#handleprevent-location-changes)
* [`NavLink`](xref:blazor/fundamentals/routing#navlink-component)
Expand Down Expand Up @@ -77,7 +77,7 @@ The following built-in Razor components are provided by the Blazor framework. Fo
* [`InputSelect`](xref:blazor/forms/input-components)
* [`InputText`](xref:blazor/forms/input-components)
* [`InputTextArea`](xref:blazor/forms/input-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#layout-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#create-a-layout-component)
* [`LayoutView`](xref:blazor/components/layouts#apply-a-layout-to-arbitrary-content-layoutview-component)
* [`NavigationLock`](xref:blazor/fundamentals/routing#handleprevent-location-changes)
* [`NavLink`](xref:blazor/fundamentals/routing#navlink-component)
Expand Down Expand Up @@ -115,7 +115,7 @@ The following built-in Razor components are provided by the Blazor framework. Fo
* [`InputSelect`](xref:blazor/forms/input-components)
* [`InputText`](xref:blazor/forms/input-components)
* [`InputTextArea`](xref:blazor/forms/input-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#layout-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#create-a-layout-component)
* [`LayoutView`](xref:blazor/components/layouts#apply-a-layout-to-arbitrary-content-layoutview-component)
* [`NavigationLock`](xref:blazor/fundamentals/routing#handleprevent-location-changes)
* [`NavLink`](xref:blazor/fundamentals/routing#navlink-component)
Expand Down Expand Up @@ -149,7 +149,7 @@ The following built-in Razor components are provided by the Blazor framework. Fo
* [`InputSelect`](xref:blazor/forms/input-components)
* [`InputText`](xref:blazor/forms/input-components)
* [`InputTextArea`](xref:blazor/forms/input-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#layout-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#create-a-layout-component)
* [`LayoutView`](xref:blazor/components/layouts#apply-a-layout-to-arbitrary-content-layoutview-component)
* [`NavLink`](xref:blazor/fundamentals/routing#navlink-component)
* [`OwningComponentBase`](xref:fundamentals/dependency-injection#utility-base-component-classes-to-manage-a-di-scope)
Expand Down Expand Up @@ -177,7 +177,7 @@ The following built-in Razor components are provided by the Blazor framework. Fo
* [`InputSelect`](xref:blazor/forms/input-components)
* [`InputText`](xref:blazor/forms/input-components)
* [`InputTextArea`](xref:blazor/forms/input-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#layout-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#create-a-layout-component)
* [`LayoutView`](xref:blazor/components/layouts#apply-a-layout-to-arbitrary-content-layoutview-component)
* [`NavLink`](xref:blazor/fundamentals/routing#navlink-component)
* [`OwningComponentBase`](xref:fundamentals/dependency-injection#utility-base-component-classes-to-manage-a-di-scope)
Expand All @@ -203,7 +203,7 @@ The following built-in Razor components are provided by the Blazor framework. Fo
* [`InputSelect`](xref:blazor/forms/input-components)
* [`InputText`](xref:blazor/forms/input-components)
* [`InputTextArea`](xref:blazor/forms/input-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#layout-components)
* [`LayoutComponentBase`](xref:blazor/components/layouts#create-a-layout-component)
* [`LayoutView`](xref:blazor/components/layouts#apply-a-layout-to-arbitrary-content-layoutview-component)
* [`NavLink`](xref:blazor/fundamentals/routing#navlink-component)
* [`OwningComponentBase`](xref:fundamentals/dependency-injection#utility-base-component-classes-to-manage-a-di-scope)
Expand Down
88 changes: 83 additions & 5 deletions aspnetcore/blazor/components/layouts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,7 @@ Some app elements, such as menus, copyright messages, and company logos, are usu

A Blazor layout is a Razor component that shares markup with components that reference it. Layouts can use [data binding](xref:blazor/components/data-binding), [dependency injection](xref:blazor/fundamentals/dependency-injection), and other features of components.

## Layout components

### Create a layout component
## Create a layout component

To create a layout component:

Expand Down Expand Up @@ -73,7 +71,7 @@ The following `DoctorWhoLayout` component shows the Razor template of a layout c

:::moniker-end

### `MainLayout` component
## `MainLayout` component

In an app created from a [Blazor project template](xref:blazor/project-structure), the `MainLayout` component is the app's [default layout](#apply-a-default-layout-to-an-app). Blazor's layout adopts the [:::no-loc text="Flexbox"::: layout model](https://developer.mozilla.org/docs/Glossary/Flexbox) ([W3C specification](https://www.w3.org/TR/css-flexbox-1/)).

Expand All @@ -94,6 +92,86 @@ In an app created from a [Blazor project template](xref:blazor/project-structure

:::moniker-end

:::moniker range=">= aspnetcore-8.0"

<!-- UPDATE 11.0 Is https://github.com/dotnet/aspnetcore/issues/52768 addressed
to resolve the following limitation? -->

## Statically-rendered layout components

When a Blazor Web App adopts per-page/component rendering (the `Routes` component doesn't specify an interactive render mode), layout components are rendered statically on the server. Applying an interactive render mode directly to a layout isn't supported because Blazor doesn't support serializing a <xref:Microsoft.AspNetCore.Components.RenderFragment> (`@Body` in this case) as a root component parameter. For example, placing `@rendermode InteractiveServer` at the top of the `MainLayout` component results in the following runtime exception:

> :::no-loc text="System.InvalidOperationException: Cannot pass the parameter 'Body' to component 'MainLayout' with rendermode 'InteractiveServerRenderMode'. This is because the parameter is of the delegate type 'Microsoft.AspNetCore.Components.RenderFragment', which is arbitrary code and cannot be serialized.":::

This applies to any layout component that inherits from <xref:Microsoft.AspNetCore.Components.LayoutComponentBase> in an app that adopts per-page/component rendering.

This scenario might be addressed in a future release of Blazor. For more information, see [[Blazor] Support serializing render fragments from SSR (`dotnet/aspnetcore` #52768)](https://github.com/dotnet/aspnetcore/issues/52768). In the meantime, you can adopt the following approach in a Blazor Web App that adopts per-page/component rendering.

Create a wrapper component that's capable of interactivity. In the following example, a wrapper component contains a [Blazor section](xref:blazor/components/sections) that can receive content from a child component.

In the `_Imports.razor` file, add an [`@using`](xref:mvc/views/razor#using) directive for sections (<xref:Microsoft.AspNetCore.Components.Sections?displayProperty=fullName>):

```razor
@using Microsoft.AspNetCore.Components.Sections
```

Create the following interactive wrapper component in the `Pages` folder.

`Pages/InteractiveWrapper.razor`:

```razor
@rendermode InteractiveServer

<div>
<SectionOutlet SectionName="top-bar" />
</div>

@ChildContent

@code {
[Parameter]
public RenderFragment? ChildContent { get; set; }
}
```

The `Counter` component can use the wrapper component and set interactive section content. In the following example, a counter button is placed in the section.

`Pages/Counter.razor`:

```razor
@page "/counter"
@rendermode InteractiveServer

<InteractiveWrapper>

<SectionContent SectionName="top-bar">
<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
</SectionContent>

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

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

</InteractiveWrapper>

@code {
private int currentCount = 0;

private void IncrementCount()
{
currentCount++;
}
}
```

Other components around the app can also wrap content in the `InteractiveWrapper` component and set interactive section content.

:::moniker-end

## Apply a layout

### Make the layout namespace available
Expand Down Expand Up @@ -220,7 +298,7 @@ Specify the default app layout in the <xref:Microsoft.AspNetCore.Components.Rout
<RouteView RouteData="routeData" DefaultLayout="typeof({LAYOUT})" />
```

In the preceding example, the `{LAYOUT}` placeholder is the layout (for example, `DoctorWhoLayout` if the layout file name is `DoctorWhoLayout.razor`). You may need to idenfity the layout's namespace depending on the .NET version and type of Blazor app. For more information, see the [Make the layout namespace available](#make-the-layout-namespace-available) section.
In the preceding example, the `{LAYOUT}` placeholder is the layout (for example, `DoctorWhoLayout` if the layout file name is `DoctorWhoLayout.razor`). You may need to identify the layout's namespace depending on the .NET version and type of Blazor app. For more information, see the [Make the layout namespace available](#make-the-layout-namespace-available) section.

Specifying the layout as a default layout in the <xref:Microsoft.AspNetCore.Components.Routing.Router> component's <xref:Microsoft.AspNetCore.Components.RouteView> is a useful practice because you can override the layout on a per-component or per-folder basis, as described in the preceding sections of this article. We recommend using the <xref:Microsoft.AspNetCore.Components.Routing.Router> component to set the app's default layout because it's the most general and flexible approach for using layouts.

Expand Down
5 changes: 5 additions & 0 deletions aspnetcore/blazor/components/render-modes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -576,6 +576,11 @@ Non-serializable component parameters, such as child content or a render fragmen

> :::no-loc text="System.InvalidOperationException: Cannot pass the parameter 'ChildContent' to component 'SharedMessage' with rendermode 'InteractiveServerRenderMode'. This is because the parameter is of the delegate type 'Microsoft.AspNetCore.Components.RenderFragment', which is arbitrary code and cannot be serialized.":::

<!-- UPDATE 11.0 Is https://github.com/dotnet/aspnetcore/issues/52768 addressed
to resolve the following limitation? -->

The same thing happens if you attempt to adopt interactive rendering in a layout that inherits from <xref:Microsoft.AspNetCore.Components.LayoutComponentBase>, such as the app's `MainLayout` component, in an app that adopts per-page/component rendering. For more information, see <xref:blazor/components/layouts#statically-rendered-layout-components>.

To circumvent the preceding limitation, wrap the child component in another component that doesn't have the parameter. This is the approach taken in the Blazor Web App project template with the `Routes` component (`Components/Routes.razor`) to wrap the <xref:Microsoft.AspNetCore.Components.Routing.Router> component.

`WrapperComponent.razor`:
Expand Down