Templating components with RenderFragments

So far we've created components that generate 100% of their rendered output based on parameters, but components aren't always that simple. Sometimes we need to create components that mix consumer-supplied mark-up with their own rendered output.

It would be very messy (not to mention unmanageable) to pass content to a component as an HTML encoded string parameter:

<Collapsible content="Lots of encoded HTML for your entire view here"/>

And, in addition to the maintenance nightmare, the embedded HTML could only be basic HTML mark-up too, no Blazor components. Basically, it'd be useless, and obviously that's not how it should be done. The correct approach is to use a RenderFragment.

Child content

If we create a new component named Collapsible (a completely empty .razor file) we can, as you have already seen, consume that in a page (such as Components/Pages/Home.razor), like so:

<Collapsible/>

But what if we want to embed some content? Give it a try and look at the error in your build output or browser's console.

<Collapsible>Hello world!</Collapsible>

System.InvalidOperationException: Object of type 'TemplatedComponents.Components.Collapsible' does not have a property matching the name 'ChildContent'.

This error is detected at compile time in modern Blazor, so you will see it in the build output or IDE before running the app.

The RenderFragment class

Now change the Collapsible component so that it has a property named ChildContent, a type of RenderFragment, and make sure it is decorated with a [Parameter] attribute.

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

These are the criteria Blazor uses to inject embedded content into a component. The embedded content may be anything you wish; plain text, HTML elements, more razor mark-up (including more components), and the content of that embedded content may be output anywhere in your component's mark-up simply by adding @ChildContent.

<div class="row">
	<a href="#" @onclick=Toggle class="col-12">@ActionText</a>
	@if (!Collapsed)
	{
		<div class="col-12 card card-body">
			@ChildContent
		</div>
	}
</div>

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

	[Parameter]
	public bool Collapsed { get; set; }

	string ActionText { get => Collapsed ? "Expand" : "Collapse"; }

	void Toggle()
	{
		Collapsed = !Collapsed;
	}
}

Multiple render fragments

When we write mark-up inside a component, Blazor will assume it should be assigned to a Parameter on the component that is descended from the RenderFragment class and is named ChildContent. If we wish to use a different name, or multiple render fragments, then we must explicitly specify the parameter's name in our mark-up.

<MyComponent>
  <Header>
    <h1>The header</h1>
  </Header>
  <Footer>
    This is the footer
  </Footer>
  <ChildContent>
    The ChildContent render fragment must now be explicitly named because we have
    more than one render fragment parameter in MyComponent.

    It doesn't have to be named ChildContent.
  </ChildContent>
</MyComponent>

In the preceding example we only need to explicitly specify <ChildContent> because we have explicitly used one or more other render fragments (Header and Footer). If we don't want to specify a <Header> and a <Footer> then there would be no need to name <ChildContent> explicitly, Blazor will assume that all mark-up within between <MyComponent> and </MyComponent> is the render fragment for ChildContent.

See Passing data to RenderFragments for more information.

Render-mode implications

Templated components with RenderFragment work across all Blazor render modes: Static Server Rendering, Interactive Server, Interactive WebAssembly, and Interactive Auto. The @ChildContent is rendered as part of the component's output tree, so it inherits the component's render mode. If a component is interactive, its child content is interactive too. If a component is statically rendered, the child content is also static.