How to use Block List and Block Grid in Umbraco

Block List or Block Grid?

• Block List: blocks stacked one after another, such as a hero, then text, then a quote. Simple for editors and the right choice for most pages.
• Block Grid: blocks placed in a layout grid with columns and nested areas. Use it when editors need real control over layout.

Each block is an element type: a document type that's used for blocks rather than pages.

Step 1: Create the element types

1. Go to Settings › Document Types › + › Element Type.
2. Create Hero Block (alias heroBlock) with heading (Textstring), text (Textarea) and image (Media Picker).
3. Create Text Block (alias textBlock) with text (Rich Text Editor).

Step 2: Create the Block List data type

1. Settings › Data Types › + › Data Type. Name it Page Blocks and choose Block List.
2. Click Add Block and pick Hero Block, then add Text Block.
3. Optionally set a label for each block, such as {=heading}, so editors can tell blocks apart.
4. Save, then add a property called Main content (alias mainContent) using Page Blocks to your page's document type.

Step 3: Render the list

In your page template, one line renders every block in order:

@await Html.GetBlockListHtmlAsync(Model, "mainContent")

With Models Builder you can also write @await Html.GetBlockListHtmlAsync(Model.MainContent).

Step 4: One partial view per block

Umbraco looks for a partial named after each block's element type alias in Views/Partials/blocklist/Components/:

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.BlockListItem>
@{
    var content = Model.Content;
    var image = content.Value<Umbraco.Cms.Core.Models.MediaWithCrops>("image");
}
<section class="hero">
    @if (image is not null)
    {
        <img src="@image.GetCropUrl(width: 1600, height: 600)" alt="@image.Value("altText")">
    }
    <h2>@content.Value("heading")</h2>
    <p>@content.Value("text")</p>
</section>

Model.Content holds the block's fields. If you add settings to a block, for example a background colour, read them from Model.Settings.

Block Grid

Set up a Block Grid data type the same way, choose how many columns it has (usually 12), and allow your blocks. Render it with:

@await Html.GetBlockGridHtmlAsync(Model, "grid")

Block Grid partials live in Views/Partials/blockgrid/Components/. If a block has areas, which are nested grids inside it, render them with GetBlockGridItemAreasHtmlAsync:

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.BlockGridItem>
<div class="text-block">
    @Model.Content.Value("text")
    @await Html.GetBlockGridItemAreasHtmlAsync(Model)
</div>

Block Grid needs layout CSS. It outputs CSS custom properties for the number of columns and each block's column span. Umbraco's documentation provides a default stylesheet, blockgridlayout.css, that you can copy into wwwroot/css and include in your layout, or you can write your own grid using those properties.

Common problems

• Nothing renders: check the property alias in GetBlockListHtmlAsync matches exactly.
• "Partial view not found": the file name must match the element type alias, such as heroBlock.cshtml, including its capital letters.
• Editors see "Unnamed block": add a label to each block in the data type.