Blazor layout sections

aspnetcore/blazor/components/layouts.md

@@ -367,6 +367,67 @@ The following rendered HTML markup is produced by the preceding nested layout. E
 
 When routable components are integrated into a Razor Pages app, the app's shared layout can be used with the components. For more information, see <xref:blazor/components/prerendering-and-integration>.
 
+:::moniker range=">= aspnetcore-8.0"
+
+## Layout sections
+
+To control the content in layout Razor components from child Razor components, Blazor supports *sections* using the following built-in components:
+
+* `SectionOutlet`: Renders content provided by `SectionContent` components with matching `SectionName` or `SectionId` arguments. Two or more `SectionOutlet` components can't have the the same `SectionName` or `SectionId`.
+
+* `SectionContent`: Provides content as a <xref:Microsoft.AspNetCore.Components.RenderFragment> to `SectionOutlet` components with a matching `SectionName` or `SectionId`. If several `SectionContent` components have the same `SectionName` or `SectionId`, the matching `SectionOutlet` component renders the content of the last rendered `SectionContent`.
+
+In the following example, the app's main layout component implements an increment counter button for the app's `Counter` component.
+
+In the `MainLayout` component (`Shared/MainLayout.razor`), place a `SectionOutlet` component and pass a string to the `SectionName` parameter to indicate the section's name. The following example uses the section name `topbar`:
+
+```razor
+<SectionOutlet SectionName="topbar" />
+```
+
+In the `Counter` component (`Pages/Counter.razor`), create a `SectionContent` component and pass the matching string (`topbar`) to its `SectionName` parameter:
+
+```razor
+<SectionContent SectionName="topbar">
+    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
+</SectionContent>
+```
+
+When the app is run, the `MainLayout` component renders the increment count button from the `Counter` component where the `SectionOutlet` component is placed.
+
+Instead of using a named section, you can pass a static `object` with the `SectionId` parameter to identify the section. The following example also implements an increment counter button for the app's `Counter` component in the app's main layout.
+
+Add a `TopbarSection` static `object` to the `MainLayout` component in an `@code` block:
+
+```razor
+@code {
+    internal static object TopbarSection = new();
+}
+```
+
+In the `MainLayout` component's Razor markup, place a `SectionOutlet` component and pass `TopbarSection` to the `SectionId` parameter to indicate the section:
+
+```razor
+<SectionOutlet SectionId="TopbarSection" />
+```
+
+Add a `SectionContent` component to the app's `Counter` component that renders an increment count button. Use the `MainLayout` component's `TopbarSection` section static `object` as the `SectionId` (`MainLayout.TopbarSection`).
+
+In `Pages/Counter.razor`:
+
+```razor
+<SectionContent SectionId="MainLayout.TopbarSection">
+    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
+</SectionContent>
+```
+
+When the app is run, the `MainLayout` component renders the increment count button where the `SectionOutlet` component is placed.
+
+> [!NOTE]
+> `SectionOutlet` and `SectionContent` components can only set either `SectionId` or `SectionName`, not both.
+
+:::moniker-end
+
 ## Additional resources
 
 * <xref:mvc/views/layout>