BlockPreview

BlockPreview enables easy to use rich HTML backoffice previews for the Umbraco Block Grid, Block List and Rich Text editors, with full support for both Razor views and ViewComponents.

Supported Versions

Note

v5.x supports Umbraco v17

v4.x supports Umbraco v16

v1.x supports Umbraco v10.x - v13.x

To understand more about which Umbraco CMS versions are actively supported by Umbraco HQ, please see Umbraco's Long-term Support (LTS) and End-of-Life (EOL) policy.

Installation

The Umbraco v17 version of this package is available via NuGet.

To install the package, you can use either .NET CLI:

dotnet add package Umbraco.Community.BlockPreview --version 5.0.0

or the NuGet Package Manager:

Install-Package Umbraco.Community.BlockPreview -Version 5.0.0

Quick Start

Important

BlockPreview requires strongly-typed models (classes with the [PublishedModel] attribute) to be compiled into your application.

Supported configurations:

• SourceCodeAuto or SourceCodeManual - Models are generated as .cs files and compiled into your assembly
• InMemoryAuto - Models are generated at runtime (development only, requires Umbraco.Cms.DevelopmentMode.Backoffice)

If you are using Limbo.Umbraco.ModelsBuilder, the default configuration is to have ModelsMode set to nothing. Once configured, generate models in the backoffice as normal.

Once models are compiled into your assembly, you can deploy with ModelsMode=Nothing to disable runtime regeneration - the compiled model types will still work with BlockPreview.

BlockPreview can be configured in the Program.cs file, before the call to the .Build() method:

+using Umbraco.Community.BlockPreview.Extensions;

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
+   .AddBlockPreview(options =>
+   {
+       options.BlockGrid = new()
+       {
+           Enabled = true,
+           ContentTypes = [RichTextBlock.ModelTypeAlias]
+       };
+
+       options.BlockList = new()
+       {
+           Enabled = true
+       };
+
+       options.RichText.Enabled = false;
+   })
    .Build();

Alternatively, it can be configured in appsettings.json:

{
  "BlockPreview": {
    "BlockGrid": {
      "Enabled": true,
      "ContentTypes": ["richTextBlock"]
    },
    "BlockList": {
      "Enabled": true
    },
    "RichText": {
      "Enabled": false
    }
  }
}

Documentation

📖 Configuration Guide - Detailed configuration options, custom view locations, and stylesheet loading

📖 Usage Guide - How to use BlockPreview in your views and editors

📖 Advanced Customization - Custom services, request enrichers, and extensibility

Contribution Guidelines

To raise a new bug, create an issue on the GitHub repository. To fix a bug or add new features, fork the repository and send a pull request with your changes. Feel free to add ideas to the repository's issues list if you would to discuss anything related to the library.

Using the Test Sites

The repo comes with a test site for Umbraco 17. The site is configured with uSync out of the box to get you up and running with a test site quickly. Use the following credentials to log into the back office:

Username: admin@example.com
Password: 1234567890

Who do I talk to?

This project is maintained by Rick Butterfield and contributors. If you have any questions about the project please get in touch on Bluesky, or by raising an issue on GitHub.

Credits

This package is entirely based on the amazing work done by Dave Woestenborghs for 24days in Umbraco 2021. His code has been extended to support the new Block Grid editor in v10.4+ and turned into this package.

Matthew Wise also wrote a great article for 24days in Umbraco 2022 which added the ability to surface ViewComponents and has allowed his code to be contributed.

Ben White contributed the RequestEnricher allowing users to customise View Location and runtime stylesheet loading.

License

Copyright © 2022-2025 Rick Butterfield, and other contributors.

Licensed under the MIT License.