Bartosz Sekula
Mar 28, 2023
(10 votes)

Official List property support


Until now users were able to store list properties in three ways:

All those approaches had its own issues and limitations.

The first one's obvious limitation was that it was only able to operate on very basic types. On the other hand it provided a nice editing experience with an inline value editor and autosave.

The next one was much more powerful because it allowed the user to use any kind of POCO and then render the list in a tabular way:


and let the user edit each item from within a dialog:


However this approach also had a few issues:

  • Property values are serialized to JSON and stored as plain string in the database
  • Permanent links are not validated
  • Some things like import/export, default values, custom metadata extenders need to be implemented manually

Finally the approach with using ContentArea or a list of ContentReference in theory solves all those issues because the editor has the ability to define the block list item anyhow and is able to use existing properties, however each list item is a separate IContent instance which has its own publishing lifecycle. In addition it also goes through the same approval process, can be included in a project as project item etc.

Because of the fact that each block is a separate IContent it is not possible to easily preview the changes or publish all items as once.

There were several attempts to solving this issue, one of them being the Block Enhancements Labs package:

The new list property

In EPiServer.CMS 12.18.0 we are releasing a brand new list property which solves all the issues outlined above.

Adding a list property is as simple as:

public virtual IList<ContactBlock> Contacts { get; set; }

Where ContactBlock can be defined like this:

[ContentType(AvailableInEditMode = false, GUID = "38d57768-e09e-4da9-90df-54c73c61b270")]  
public class ContactBlock : BlockData  
   //block properties  

What is important here is the fact that each ContactBlock instance will not be a content item of its own but will be stored inside its parent.

That fact has several implications:

  • Editor no longer needs to switch context to edit those inline blocks
  • Inline blocks do not have publishing lifecycle meaning that whenever any list item is changed the user the editor will see a new version of the current content being created
  • List items will inherit approval sequence from their parent, it is the parent content that has to be reviewed and approved
  • List items will not be included in projects, only their parent content as a whole

The editor of such contact block list will look like this:

Of course, having the ability to make the blocks inline is the primary use case of the new List<T> however it is capable of storing any kind of property type inside.

Users can still utilize basic types like:

public virtual IList<int> Numbers { get; set; }

public virtual IList<string> Strings { get; set; }

public virtual IList<DateTime> Dates { get; set; }

But it is also possible to use more complex types:

public virtual IList<XHtmlString> XHtmlStrings { get; set; }

Or for example create a list of images or videos:

public virtual IEnumerable<ContentReference> Images { get; set; }

Which will be rendered like this:

Please note that the property is annotated with a new attribute ListItemUIHintAttribute which works the same as regular UIHint but applies to the generic type of the list item.

So we are telling the List property to use UIHint.Image for individual items.

It is still possible to use UIHint("YourCustomListEditor") if you have your own editor.


No special attributes or techniques are needed in order to render a list of any property types.

The only thing needed is to provide a display template for a single item and the CMS will do the rest by wrapping each item in a list item.

public virtual IList<EditorialBlock> Blocks { get; set; }

You will just need to provide EditorialBlock.cshtml which could look like this:

@model EditorialBlock

<div class="clearfix" @Html.EditAttributes(x => x.MainBody)>
    @Html.DisplayFor(x => Model.MainBody)

And to render the `Blocks` property on the page you can use either HtmlHelpers package:

@model MyPage

@Html.PropertyFor(x => x.EditorialBlocks)

Or the new TagHelpers package:

@model MyPage

<div epi-property="EditorialBlocks" />


The data model behind the scenes is much different from the previous implementations which always were based on some sort of JSON serialization.

There is no automatic way to migrate from the old model to the new one and all migrations might different from case to case but let's imagine a hypothetical scenario like this:

Let's say we have a page MyPage.cs with a single property inside:

public class MyPage : PageData 
   [EditorDescriptor(EditorDescriptorType = typeof(CollectionEditorDescriptor<Person>))]
   public virtual IList<Person> PersonList { get; set; }

public class Person
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int Age { get; set; }
    public string Email { get; set; }

public class PersonListProperty : PropertyList<Person>
    public PersonListProperty()
        _objectSerializer = _objectSerializerFactory.Service.GetSerializer(KnownContentTypes.Json);

    private Injected<IObjectSerializerFactory> _objectSerializerFactory;

    private IObjectSerializer _objectSerializer;

    protected override Person ParseItem(string value)
        return _objectSerializer.Deserialize<Person>(value);

The property would look like this in Edit Mode:

In order to migrate to the new property and use the new inline editor we would have to:

Define a new PersonBlock type and mark it as AvailableInEdit = false

[ContentType(AvailableInEditMode = false, GUID = "11157768-e09e-4da9-90df-54c73c61b270")] 
public class PersonBlock : BlockData
    public virtual string FirstName { get; set; }
    public virtual string LastName { get; set; }
    public virtual int Age { get; set; }
    public virtual string Email { get; set; }

In order to use it on MyPage:

public class MyPage : PageData 
   public virtual IList<PersonBlock> PersonsNew { get; set; }

And the new editing experience will look like this:

Please note that it is no longer necessary to define your own property type.

In order to migrate from IList<Person> to IList<PersonBlock> a custom piece of code which iterates over all instances of MyPage analyzes what is inside PersonList property and then uses the same values to create an a list of PersonBlock instances.

Next improvements coming up

We are planning to take it even further and allow to inline blocks into Content Area as well so stay tuned for next updates on that matter.

Eventually we will turn off `Quick edit` command and promote the new Inline Blocks which no longer need any kind of tricks to keep their publishing lifecycle synchonized with their parent.

We will also not need any commands like `Publish page with blocks` 

Obsoleting EPiServer.Labs.BlockEnhancements

The whole idea of `inlining` the blocks into page came up as part of our Labs initiative which turned out to be highly successful 

Now, since most of Labs functionality ends up in the official package it is time to deprecate it.

Mar 28, 2023


huseyinerdinc Mar 28, 2023 01:46 PM

This is a long awaited feature which creates a huge value for the clients!🥳

Ove Lartelius
Ove Lartelius Mar 29, 2023 09:26 AM

Nice feature and a really good blog post! Cheers!

Surjit Bharath
Surjit Bharath Mar 29, 2023 01:22 PM

This was a great write up and you've also included a technique for the migration. Thanks for this!

Pierre Apr 12, 2023 04:07 PM

Thank you! This will be really very useful ! I already started to use it in our new project.

However be aware it seems there is a important bug inside the version 12.18.0: if you have an inline Block in a page you can't use
"public virtual IList<string> myBlockProperty" in a block property the new UI will not show up. It looks like a regression as it was working before.

Bartosz Sekula are you aware of this issue ?

Bartosz Sekula
Bartosz Sekula Apr 28, 2023 07:52 AM

Pierre, the issue has been fixed in

PuneetGarg May 24, 2023 07:17 AM

Thank you sharing this is important and very knowledge full. 

Shamrez Iqbal
Shamrez Iqbal May 26, 2023 09:20 AM

@bartosz Is it possible to get the ID of the containing page for a block which is defined inside such a list. 

I need it inside a selectionfactory on a property defined in the block definition but the extended metadata paramater does not contain any reference to the containing page.

QuirijnLangedijk Jun 2, 2023 08:53 AM

Great future! But, it'd be great if drag-and-drop ordening was brought back (like IList<> used to work), moving items by 1 position per 2 clicks doesn't feel as user friendly as being able to reorder them by dragging/dropping, especially for longer lists

Please login to comment.
Latest blogs
Extended SelectionFactory

In one of my previous articles I described new Color Picker widget. Today I’d like to show another simple property. I prepared extended version of...

Grzegorz Wiecheć | Jun 7, 2023 | Syndicated blog

Unlock Creativity with Text Generation

Need fresh and innovative content ideas? The Epicweb.Optimizely.AIAssistant Addon has got you covered with its text generation feature. In this blo...

Luc Gosso (MVP) | Jun 6, 2023 | Syndicated blog

Breaking Language Barriers with Multilingual Text Translation

In today's globalized world, effective communication across languages is essential. The Epicweb.Optimizely.AIAssistant Addon makes language...

Luc Gosso (MVP) | Jun 6, 2023 | Syndicated blog

Optimizely Search & Navigation - Get autocomplete suggestions in right language

When you are using Optimizely Search & Navigation (Find) to help you generate autocomplete suggestions server side in a multi-language scenario it...

Allan Thraen | Jun 5, 2023 | Syndicated blog