("myGrid");
// get the number of columns defined for the grid
var gridColumns = grid.GridColumns;
// iterate the block items
foreach (var item in grid)
{
// get the content and settings of the block
var content = item.Content;
var settings = item.Settings;
// get the areas of the block
var areas = item.Areas;
// get the dimensions of the block
var rowSpan = item.RowSpan;
var columnSpan = item.ColumnSpan;
// render the block data
@(content.Value("title"))
This block is supposed to span @rowSpan rows and @columnSpan columns
}
}
```
{% endcode %}
## Using Block Grid with the Delivery API
When using Block Grid in a headless scenario with the [Content Delivery API](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api), the property outputs a structured JSON representation instead of rendered HTML.
The JSON structure includes:
* `gridColumns` - The number of columns configured for the grid (typically 12)
* `items` - An array of block items, each containing:
* `content` - The block's content data
* `settings` - The block's settings data (if configured)
* `rowSpan` and `columnSpan` - Layout dimensions for the block
* `areaGridColumns` - Number of columns for nested areas
* `areas` - Array of nested areas within the block, each containing their own items
Your frontend application is responsible for:
* Parsing the grid layout structure
* Implementing CSS Grid or an equivalent layout system
* Rendering blocks recursively to handle nested areas
* Handling responsive behavior
For detailed information about the JSON structure and property expansion options, see [Property expansion and limiting](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api/property-expansion-and-limiting#block-grid).
## Write a Custom Layout Stylesheet
The default layout stylesheet is using CSS Grid. This can be modified to fit your implementation and your project.
### Adjusting the Default Layout Stylesheet
To make additions or overwrite parts of the default layout stylesheet, import the default stylesheet at the top of your own file.
```css
@import 'css/umbblockgridlayout.css';
```
You need to copy the Default Layout Stylesheet to your frontend. You can download the default layout stylesheet from the link within the DataType, we recommend putting the file in the `css` folder, example: `wwwroot/css/umbraco-blockgridlayout.css`.
### Write a new Layout Stylesheet
In this case, you would have to write the layout from scratch.
You are free to pick any style, meaning there is no requirement to use CSS Grid. It is, however, recommended to use CSS Grid to ensure complete compatibility with the Umbraco backoffice.
### CSS Class structure and available data
When extending or writing your own layout, you need to know the structure and what data is available.
For example: You can use the below HTML structure:
```html
```
## Build a Custom Backoffice View
Building Custom Views for Block representations in Backoffice is based on the same API for all Block Editors.
[Read about building a Custom View for Blocks here](https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types/block-custom-view)
## Creating a Block Grid programmatically
In this example, we will be creating content programmatically for a "spot" Blocks in a Block Grid.
1. Create an element type to represent block content called **Spot Element** with the following properties:
* A property called **title** with the editor of **Textstring**
* A property called **text** with the editor of **Textstring**
2. Create an element type to represent block content called **Spot Settings** with the following properties:
* A property called **featured** with the editor of **True/false**.
3. Add a property called **blockGrid** in a Document Type.
4. Select **Block Grid** as the property editor.
5. Click **Add** in the **Blocks** Settings and select **Spot Element**.
6. Select **Spot Settings** in the **Settings model** field.
The raw input data for the spots looks like this:
```csharp
new[]
{
new { Title = "Item one", Text = "This is item one", Featured = false, ColumnSpan = 12, RowSpan = 1 },
new { Title = "Item two", Text = "This is item two", Featured = true, ColumnSpan = 6, RowSpan = 2 }
}
```
The resulting JSON object stored for the Block Grid will look like this:
```json
{
"contentData":[
{
"contentTypeKey":"fd01539a-5bcf-48f7-aee5-8ad925c75902",
"udi":null,
"key":"019f2a7a-35b4-45b3-b867-910b3f340f25",
"values":[
{
"editorAlias":"Umbraco.TextBox",
"culture":null,
"segment":null,
"alias":"title",
"value":"Item one"
},
{
"editorAlias":"Umbraco.TextBox",
"culture":null,
"segment":null,
"alias":"text",
"value":"This is item one"
}
]
},
{
"contentTypeKey":"fd01539a-5bcf-48f7-aee5-8ad925c75902",
"udi":null,
"key":"063f8062-8610-441a-97f1-ea6d73fe2678",
"values":[
{
"editorAlias":"Umbraco.TextBox",
"culture":null,
"segment":null,
"alias":"title",
"value":"Item two"
},
{
"editorAlias":"Umbraco.TextBox",
"culture":null,
"segment":null,
"alias":"text",
"value":"This is item two"
}
]
}
],
"settingsData":[
{
"contentTypeKey":"03c43074-a4ba-4bd2-92b1-c3a35a0eed4d",
"udi":null,
"key":"5b2d74bc-3e85-4aa3-b684-4b1f11522d7c",
"values":[
{
"editorAlias":"Umbraco.TrueFalse",
"culture":null,
"segment":null,
"alias":"featured",
"value":0
}
]
},
{
"contentTypeKey":"03c43074-a4ba-4bd2-92b1-c3a35a0eed4d",
"udi":null,
"key":"1c6599fc-6558-4a0b-9da8-4f002925f59f",
"values":[
{
"editorAlias":"Umbraco.TrueFalse",
"culture":null,
"segment":null,
"alias":"featured",
"value":1
}
]
}
],
"expose":[
{
"contentKey":"019f2a7a-35b4-45b3-b867-910b3f340f25",
"culture":null,
"segment":null
},
{
"contentKey":"063f8062-8610-441a-97f1-ea6d73fe2678",
"culture":null,
"segment":null
}
],
"Layout":{
"Umbraco.BlockGrid":[
{
"columnSpan":12,
"rowSpan":1,
"areas":[
],
"contentUdi":null,
"settingsUdi":null,
"contentKey":"019f2a7a-35b4-45b3-b867-910b3f340f25",
"settingsKey":"5b2d74bc-3e85-4aa3-b684-4b1f11522d7c"
},
{
"columnSpan":12,
"rowSpan":1,
"areas":[
],
"contentUdi":null,
"settingsUdi":null,
"contentKey":"063f8062-8610-441a-97f1-ea6d73fe2678",
"settingsKey":"1c6599fc-6558-4a0b-9da8-4f002925f59f"
}
]
}
}
```
For each item in the raw data, we need to create:
* One `contentData` entry with the *title* and *text*.
* One `settingsData` entry with the *featured* value (the checkbox expects `"0"` or `"1"` as data value).
* One `layout` entry with the desired column and row spans.
All `contentData` and `layoutData` entries need their own unique `Udi` as well as the ID (key) of their corresponding Element Types. In this sample, we only have one Element Type for content (`spotElement`) and one for settings (`spotSettings`). In a real life scenario, there could be any number of Element Type combinations.
7. Create a class called **Model.cs** containing the following to transform the raw data into Block Grid-compatible JSON:
{% code title="Models.cs" lineNumbers="true" %}
```csharp
using System.Text.Json.Serialization;
namespace My.Site.Models;
// this is the "root" of the block grid data
public class BlockGridData
{
public BlockGridData(BlockGridElementData[] contentData, BlockGridElementData[] settingsData, BlockGridExposeData[] expose, BlockGridLayout layout)
{
ContentData = contentData;
SettingsData = settingsData;
Expose = expose;
Layout = layout;
}
[JsonPropertyName("contentData")]
public BlockGridElementData[] ContentData { get; }
[JsonPropertyName("settingsData")]
public BlockGridElementData[] SettingsData { get; }
[JsonPropertyName("expose")]
public BlockGridExposeData[] Expose { get; }
[JsonPropertyName("Layout")]
public BlockGridLayout Layout { get; }
}
// this represents an item in the block grid content or settings data collection
public class BlockGridElementData
{
public BlockGridElementData(Guid contentTypeKey, Guid key, BlockGridValueData[] values)
{
ContentTypeKey = contentTypeKey;
Key = key;
Values = values;
}
[JsonPropertyName("contentTypeKey")]
public Guid ContentTypeKey { get; }
[JsonPropertyName("key")]
public Guid Key { get; }
[JsonPropertyName("values")]
public BlockGridValueData[] Values { get; }
}
public class BlockGridValueData
{
public BlockGridValueData(string alias, string editorAlias, object? value)
{
Alias = alias;
EditorAlias = editorAlias;
Value = value;
}
[JsonPropertyName("alias")]
public string Alias { get; }
[JsonPropertyName("editorAlias")]
public string EditorAlias { get; }
[JsonPropertyName("value")]
public object? Value { get; }
}
// this represents an item in the block grid expose data collection
public class BlockGridExposeData
{
public BlockGridExposeData(Guid contentKey) => ContentKey = contentKey;
[JsonPropertyName("contentKey")]
public Guid ContentKey { get; }
}
// this is a wrapper for the block grid layout, purely required for correct serialization
public class BlockGridLayout
{
public BlockGridLayout(BlockGridLayoutItem[] layoutItems) => LayoutItems = layoutItems;
[JsonPropertyName("Umbraco.BlockGrid")]
public BlockGridLayoutItem[] LayoutItems { get; }
}
// this represents an item in the block grid layout collection
public class BlockGridLayoutItem
{
public BlockGridLayoutItem(int columnSpan, int rowSpan, Guid contentKey, Guid settingsKey)
{
ColumnSpan = columnSpan;
RowSpan = rowSpan;
ContentKey = contentKey;
SettingsKey = settingsKey;
}
[JsonPropertyName("columnSpan")]
public int ColumnSpan { get; }
[JsonPropertyName("rowSpan")]
public int RowSpan { get; }
[JsonPropertyName("contentKey")]
public Guid ContentKey { get; }
[JsonPropertyName("settingsKey")]
public Guid SettingsKey { get; }
[JsonPropertyName("areas")]
// areas are omitted from this sample for abbreviation
public object[] Areas { get; } = [];
}
```
{% endcode %}
9. By injecting [ContentService](https://apidocs.umbraco.com/v16/csharp/api/Umbraco.Cms.Core.Services.ContentService.html) and [ContentTypeService](https://apidocs.umbraco.com/v16/csharp/api/Umbraco.Cms.Core.Services.ContentTypeService.html) into an API controller, we can transform the raw data into Block Grid JSON. It can then be saved to the target content item. Create a class called **BlockGridTestController.cs** containing the following:
{% code title="BlockGridTestController.cs" lineNumbers="true" %}
```csharp
using Microsoft.AspNetCore.Mvc;
using My.Site.Models;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.Serialization;
using Umbraco.Cms.Core.Services;
namespace My.Site.Controllers;
[ApiController]
[Route("/umbraco/api/blockgridtest")]
public class BlockGridTestController : Controller
{
private readonly IContentService _contentService;
private readonly IContentTypeService _contentTypeService;
private readonly IJsonSerializer _serializer;
public BlockGridTestController(IContentService contentService, IContentTypeService contentTypeService, IJsonSerializer serializer)
{
_contentService = contentService;
_contentTypeService = contentTypeService;
_serializer = serializer;
}
// POST: /umbraco/api/blockgridtest/create
[HttpPost("create")]
public ActionResult Create()
{
// get the item content to modify
IContent? content = _contentService.GetById(Guid.Parse("7ed0bd1f-2a52-4b45-9811-2560b907fe48"));
if (content == null)
{
return NotFound("Could not find the content item to modify");
}
// get the element types for spot blocks (content and settings)
IContentType? spotContentType = _contentTypeService.Get("spotElement");
IContentType? spotSettingsType = _contentTypeService.Get("spotSettings");
if (spotContentType == null || spotSettingsType == null)
{
return NotFound("Could not find one or more content types for block data");
}
// this is the raw data to insert into the block grid
var rawData = new[]
{
new { Title = "Item one", Text = "This is item one", Featured = false, ColumnSpan = 12, RowSpan = 1 },
new { Title = "Item two", Text = "This is item two", Featured = true, ColumnSpan = 6, RowSpan = 2 }
};
// build the individual parts of the block grid data from the raw data
var contentData = new List();
var settingsData = new List();
var exposeData = new List();
var layoutItems = new List();
foreach (var data in rawData)
{
// generate new keys for block content and settings
var contentKey = Guid.NewGuid();
var settingsKey = Guid.NewGuid();
// create new content data
var contentValues = new BlockGridValueData[]
{
new("title", "Umbraco.TextBox", data.Title),
new("text", "Umbraco.TextBox", data.Text),
};
contentData.Add(new BlockGridElementData(spotContentType.Key, contentKey, contentValues));
// create new settings data
var settingValues = new BlockGridValueData[]
{
new("featured", "Umbraco.TrueFalse", data.Featured ? "1" : "0"),
};
settingsData.Add(new BlockGridElementData(spotSettingsType.Key, settingsKey, settingValues));
// create a new expose item
exposeData.Add(new BlockGridExposeData(contentKey));
// create a new layout item
layoutItems.Add(new BlockGridLayoutItem(data.ColumnSpan, data.RowSpan, contentKey, settingsKey));
}
// construct the block grid data from layout, content and settings
var blockGridData = new BlockGridData(
[.. contentData],
[.. settingsData],
[.. exposeData],
new BlockGridLayout([.. layoutItems]));
// serialize the block grid data as JSON and save it to the "blockGrid" property on the content item
var propertyValue = _serializer.Serialize(blockGridData);
content.SetValue("blockGrid", propertyValue);
_contentService.Save(content);
return Ok("Saved");
}
}
```
{% endcode %}
For the above code `IContent? content = _contentService.GetById(Guid.Parse("efba7b97-91b6-4ddf-b2cc-eef89ff48c3b"));` change the id with your content node that is using the Block Grid.
10. To test this implementation, run the project and send a `POST` request to `/umbraco/api/blockgridtest/create` after your domain name. If the result shows as **Saved**, then check your content node, and you will see the 2 spotElement contents.
*This can also be tested via Postman as well if preferred.*
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.umbraco.com/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/block-grid-editor.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
