Bartosz Sekula
Mar 28, 2023
(11 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 Vignon (Yaksa)
Pierre Vignon (Yaksa) 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

Ted Jun 16, 2023 01:44 PM

Great work - we've looked forward to this for a long time!

Is it possible to override what text is displayed for each item?

Let's say you have a lot of contacts, like the `PersonBlock` example. Each item will simply say "PersonBlock", making it difficult to find a specific item/contact.

It would be helpful if the item text could be for example the name of the person. Finding "Todd" in the list is easier than expanding all items to look for the right one. :)

Pierre Vignon (Yaksa)
Pierre Vignon (Yaksa) Jun 16, 2023 03:17 PM

@bartosz yes I confirm this specific issued was fixed in the 12.19.0, thank you!

However we noticed few other issues with this feature.

If the MyBLock of field IList<MyBLock> as [CultureSpecific] field(s) it will just not work (in contrary of single inlined MyBLock). The support answer me that I have to make the field IList<MyBlock> itself [CultureSpecific] and redo the list in other language which is not ideal. So it's an important limitation to be aware of!

Bartosz Sekula
Bartosz Sekula Jun 19, 2023 08:47 AM


It is possible to decide which property to use to render list item header:

public virtual IEnumerable<ContactBlock> ContactBlocks { get; set; }

I've updated the docs, new version will be published very soon:

Bartosz Sekula
Bartosz Sekula Jun 19, 2023 08:50 AM

Pierre, what is your expectation? Let's say you have an English version with IList<ContactBlock> and inside you have 2 contacts. What should happen after translating that page to Italian?

Ted Jun 19, 2023 08:53 AM

Fantastic news on the `ListItemHeaderProperty`, nicely done! Thanks!

Pierre Vignon (Yaksa)
Pierre Vignon (Yaksa) Jun 20, 2023 02:54 PM

@bartosz I guess I would assume it to work in the same way a solo inlined block is working ?
If the field `IList<TestBlock> ...` in the Parent Page is not `culture specific` the list will be the same in all languages but
fields of the `TestBlock` which are `culture specific` will be modifiable in all the Parent Page language. (
public virtual IList<TestBlock> TestBlockList { get; set; })
This would be the same behavior as directly adding the TestBlock in a field of ParentPage. (
public virtual TestBlock TestBlockInlined { get; set; })

It is easy to quickly test it using Alloy demo.

public class TestBlock : SiteBlockData
{ [CultureSpecific]
public virtual string MyTitle { get; set; }
// Not culture specific field:
public virtual string TestId { get; set; }

Thank you!

Wojciech Gabel
Wojciech Gabel Aug 31, 2023 02:28 PM

Hi Bartosz!
Can you elaborate on how to migrate list items? Should we use the standard GetDefault<PersonBlock> method and then Save those instances like standard blocks, using repository.Save()? How are they going to be saved? Where are they stored? Do we need to specify parent for those blocks?

Please login to comment.
Latest blogs
Performance optimization – the hardcore series – part 2

Earlier we started a new series about performance optimization, here Performance optimization – the hardcore series – part 1 – Quan Mai’s blog...

Quan Mai | Oct 4, 2023 | Syndicated blog

Our first steps into local AI

After a consumer of tools like ChatGPT and CoPilot, we as developers like to dive deeper into it. How does it work? Where to start? Can I create my...

Chuhukon | Oct 4, 2023 | Syndicated blog

Update on .NET 8 support

With .NET 8 now in release candidate stage I want to share an update about our current thinking about .NET 8 support in Optimizely CMS and Customiz...

Magnus Rahl | Oct 3, 2023

Adding Block Specific JavaScript and CSS to the body and head of the page

A common requirement for CMS implementations includes the ability to embed third party content into a website as if it formed part of the website...

Mark Stott | Oct 3, 2023

Performance optimization – the hardcore series – part 1

Hi again every body. New day – new thing to write about. today we will talk about memory allocation, and effect it has on your website performance....

Quan Mai | Oct 3, 2023 | Syndicated blog

Next level content delivery with Optimizely Graph

Optimizely introduced a new product called Optimizely Graph earlier this year. We were one of the first partners to adopt this new service in a...

Ynze | Oct 2, 2023 | Syndicated blog