This documentation platform covers only major versions of Umbraco UI Builder. If you are using an unsupported version, you need to go elsewhere.

Umbraco UI Builder is the Umbraco v10+ backoffice UI builder for custom data structures configured via a fluent API.

If you have a custom data store that you want to content manage from within Umbraco, then you can use Umbraco UI Builder. With some lines of code, you can configure a custom administration UI, and reuse many core components with a consistent look and feel.

With Umbraco UI Builder, custom backoffice integrations can now take a matter of minutes, rather than days.

Using the Documentation

This documentation is aimed at developers who have at least a basic understanding of Umbraco, as well as C#/MVC principles.

If you are new to Umbraco UI Builder, it is recommended that you start by taking a look at the Getting Started section. This provides details on the system requirements and how to install Umbraco UI Builder.

Once you have Umbraco UI Builder installed and are wondering "What next?" then you'll want to take a look at the section. This provides a quick-start example of how to configure Umbraco UI Builder.

Use the main menu to dive deeper into Umbraco UI Builder and get to know all of its features in detail. You can then jump to the specific topic you are interested in to find out more.

Finally, for all other resources/useful information you can head over to the section.

If you require assistance you can use our support channels to seek assistance.

If you want to work with a subset of data within a given collection then this is where the global filters come in handy. These allow you to define a filter to apply to all queries for a given collection.

Applying a global filter

Applying a global filter is controlled via the collections configuration.

SetFilter(Lambda whereClauseExpression) : CollectionConfigBuilder<TEntityType>

Sets the filter where clause expression. Expression must be a boolean expression.

// Example
collectionConfig.SetFilter(p => p.Current);

Umbraco UI Builder tries its best to mimic the content pipeline as closely as possible whilst sticking to public and supported APIs. This is so that the Data Type suite can be used fully for editing properties. There are some features in the Umbraco Core that are locked away in internal methods. This means that some features may not be fully supported. Below is a list of known issues to date.

Property Editors

Tags

Whilst we have support for persisting the tag's value, we don't currently have the ability to write these tags to the cmsTags DB table. This is all handled via a tagsRepository which is internal so we currently can't save to it as core does.

Multi-Node Tree Picker

When using a Multi-Node Tree Picker with an XPath filter, only filters starting with the $root placeholder will be valid. This is because all other placeholders expect the property editor to be placed on a content node, with that node being used as context.

RTE Macros

Macros in Rich Text Editors don't appear to work properly due to the preview mechanism. They save and run on the front end, but you'll get an error notification in the backoffice as it tries to render a preview.

The Block Editors (Block List/Block Grid) are not supported due to an undefined error with umbVariantContent in the $scope chain.

This page covers specific upgrade documentation for when migrating to major 13 of Umbraco UI Builder.

Version Specific Upgrade Notes History

Version 13 contains a number of breaking changes from the previous, Konstrukt product.

See the Migrate from Konstrukt to Umbraco UI Builder guide for full details.

Legacy version specific upgrade notes

You can find the version specific upgrade notes for versions out of support in the Legacy documentation on GitHub.

Umbraco UI Builder can be configured directly via the AddUIBuilder extension method on IUmbracoBuilder.

To configure Umbraco UI Builder via the AddUIBuilder extension method, you can look at the Program.cs file at the root of your web project. From within this file, before the call to AddComposers() you can add the AddUIBuilder configuration.

Alternatively, if your project is upgraded from earlier versions, you can add the configuration to the

There are different areas of the Umbraco UI that Umbraco UI Builder can be injected into. Before you get to managing your actual content you need to choose which area makes the most sense to present that data in. Then you can review how to go about configuring that particular type of area.

Choose an area type from the list below to find out more.

Beyond there might be times when you need to be able to create specific views of a collection's data. To help with this Umbraco UI Builder has different filtering mechanisms available.

Choose a filtering method from the list below to find out more.

A collection is the cornerstone Umbraco UI Builder config and it represents a collection of entities for a given data model. From this config object, you can configure everything about how this collection integrates into the UI. You can also configure how it should display in a list view as well as how it should be edited.

Get started by reviewing the basics of collection configuration.

Actions provide an API to perform custom tasks against a collection and its entities from multiple locations in the UI. Examples: menu actions, bulk actions, or individual table row actions.

Get started with actions by learning about the basics.

Umbraco UI Builder is installed via the NuGet package manager by issuing the following command in your web project.

If you wish to install Umbraco UI Builder into a class library without the UI elements, you can add a reference to the Umbraco.UIBuilder.Startup package instead.

Alternatively, you can also find and install the NuGet package via the NuGet Package Manager graphical user interface (GUI) in Visual Studio.

See the for details on how to install a license.

Cards provide an API to display basic summary information in a card-based format and are useful for displaying key metrics about a collection.

Cards can be defined in one of two ways:

If needed to collect sensitive information in a collection but don't want to persist in a plain text format to the data storage mechanism. Umbraco UI Builder can help with this by allowing you to define properties as encrypted. After which any time the value is persisted or retrieved from persistence, Umbraco UI Builder will automatically encrypt and decrypt the value.

Adds the given property to the encrypted properties collection. Property must be of type String. When set, the property will be encrypted/decrypted on write/read respectively.

As well as the API for managing your custom data source, Umbraco UI Builder also comes with some property editors. Those property editors help you work with your data inside Umbraco content nodes.

The property editors available are:

Umbraco UI Builder comes with some inbuilt actions that are available for you to use straight away.

ExportEntityAction

Namespace Umbraco.UIBuilder.Infrastructure.Configuration.Actions

Provides a Comma-Separated Values (CSV) export functionality converting all properties to column headings and rendering each entity property values on each row.

ImportEntityAction

Namespace Umbraco.UIBuilder.Infrastructure.Configuration.Actions

Provides a Comma-Separated Values (CSV) import functionality matching column headings with entity properties and mapping row values to an entity.

Retrieving child collections in one-to-many relationships with UI Builder, can be achieved with the support of child repositories. One-to-many relations are where one parent entity of a collection is associated with multiple entities from another.

Models Representation

The models would look like this:

[TableName("Students")]
[PrimaryKey("Id")]
public class Student
{
    [PrimaryKeyColumn]
    public int Id { get; set; }

    public string FirstName { get; set; }

    public string LastName { get; set; }

    public string Email { get; set; }
}

Child Repositories

You can create child repository instances via the IRepositoryFactory and use them to retrieve information from the child collection.

Umbraco UI Builder is a commercial product. You can run an Umbraco UI Builder unrestricted locally without the need a license. Running Umbraco UI Builder on a public domain will display a warning banner in the backoffice and will limit usage to a single editable collection. To remove these restrictions, you'll need to have a valid license.

How does it work?

Licenses are sold per backoffice domain and will also work on all subdomains. If you have alternative staging/qa environment domains, additional domains can be added to the license on request.

Let's say that you have a license configured for your domain, mysite.com, and you've requested two development domains, devdomain.com and devdomain2.com.

The license will cover the following domains:

• localhost

• *.local

• *.mysite.com

There are a few differences as to what the licenses cover:

• A single license covers the installation of Umbraco UI Builder in 1 production backoffice domain, as well as in any requested development domains.

• The production domain includes all subdomains (e.g. *.mysite.com).

• The development domains work with or without the www

You can look at the pricing, features, and purchase a license on the page. On this page, you can fill out the form with your project details and requirements. A member of the Sales team will manage this process. In the process, you will need to provide all domains you wish to have covered by the license such as primary and staging/QA domains. You should then receive a license code to be installed in your solution.

If you require to add additional domains to the license, . They will manage your request and take care of the process.

Once you've purchased your license with the correct domains, you are ready to configure the license key on your Umbraco installation.

The license key should be added to your configuration using product ID: Umbraco.UIBuilder.

For detailed instructions on how to install and configure your license, including version-specific examples and additional configuration options, see the article.

This section will guide you through the key steps necessary to get you started with Umbraco UI Builder.

It is assumed that you have an Umbraco 10+ website configured, and ready to install Umbraco UI Builder.

System Requirements

At this time, the minimum requirements for using Umbraco UI Builder are as follows:

• Umbraco CMS version 10.0/12.0+

• SQL Server Database (SQLite is fine for testing, but not recommended for live deployments)

This is an add-on product to Umbraco CMS. Umbraco UI Builder follows the .

A child collection is a container for a given data model that is tied to a parent collection data model. It shares all of the Collections config builder API except child collections cannot contain further child collections.

Defining a child collection

You define a child collection by calling one of the AddChildCollection methods on a given collection config builder instance.

AddChildCollection<TChildEntityType>(Lambda idFieldExpression, Lambda fkFieldExpression, string nameSingular, string namePlural, string description, Lambda childCollectionConfig = null) : ChildCollectionConfigBuilder<TEntityType>

Adds a child collection to the current collection with the given names and description and default icons. A property accessor expression is required for both the entity ID field and FK (Foreign Key) field of the entity.

// Example
collectionConfig.AddChildCollection<Child>(c => c.Id, c => c.ParentId, "Child", "Children", "A collection of children", childCollectionConfig => {
    ...
});

AddChildCollection<TChildEntityType>(Lambda idFieldExpression, Lambda fkFieldExpression, string nameSingular, string namePlural, string description, string iconSingular, string iconPlural, Lambda childCollectionConfig = null) : ChildCollectionConfigBuilder<TEntityType>

Adds a child collection to the current collection with the given names, description and icons. A property accessor expression is required for both the entity ID field and FK (Foreign Key) field of the entity.

// Example
collectionConfig.AddChildCollection<Child>(c => c.Id, c => c.ParentId, "Child", "Children", "A collection of children", "icon-umb-users", "icon-umb-users", childCollectionConfig => {
    ...
});

Configuring a child collection

Child collections share the same API as the Collection config builder API, except child collections cannot contain further child collections. For more information check the .

Searchable properties allow you to define any String based properties on a model. They will be searchable via Umbraco UI Builder's list view and entity picker search controls.

You can also use any String based property of nested objects of a model, as long as the parent object is not null.

Defining searchable properties

AddSearchableProperty(Lambda searchablePropertyExpression) : CollectionConfigBuilder<TEntityType>

Adds the given property to the searchable properties collection.

// Example
collectionConfig.AddSearchableProperty(p => p.FirstName);
collectionConfig.AddSearchableProperty(p => p.Address.Street);

Search Expression Pattern

Up to version 13.1.6, the search was performed using the StartsWith method call. From 13.1.6 and up, search operations can be performed using the Contains method call.

Data views allow you to define multiple, pre-filtered views of the same data source. This can be useful when entities exist in different states and you want a way to toggle between them.

Defining data views

Data views are defined via the collections configuration.

AddDataView(string name, Lambda whereClauseExpression) : CollectionConfigBuilder<TEntityType>

Adds a data view with the given name and where clause filter expression. Expression must be a boolean expression.

// Example
collectionConfig.AddDataView("Active", p => p.IsActive);

AddDataView(string group, string name, Lambda whereClauseExpression) : CollectionConfigBuilder<TEntityType>

Adds a data view with the given group, name and where clause filter expression. Expression must be a boolean expression.

// Example
collectionConfig.AddDataView("Status", "Active", p => p.IsActive);

A summary dashboard is automatically displayed at the root of a defined Umbraco UI Builder section. It displays summaries of collections found within it that are told to display on the dashboard. It also provides quick links to jump to that collections list view. It can also add quickly a new entry to that collection (if the collection isn't read-only).

Showing a collection on a summary dashboard

Showing a collection in the summary dashboard is controlled via the collection configuration.

ShowOnSummaryDashboard() : CollectionConfigBuilder<TEntityType>

Sets the collection to display on the summary dashboard.

// Example
collectionConfig.ShowOnSummaryDashboard();

A child collection group is a container for other child collections. Its purpose is mainly to provide a logical grouping of multiple child collections to help with organization and an improved user experience.

Defining a child collection group

You can define a child collection group by calling one of the AddChildCollectionGroup methods on a given collection config builder instance.

AddChildCollectionGroup(string name, Lambda childCollectionGroupConfig = null) : ChildCollectionGroupConfigBuilder

Adds a child collection group to the current collection with the given name and default icon.

// Example
collectionConfig.AddChildCollectionGroup("Family", childCollectionGroupConfig => {
    ...
});

AddChildCollectionGroup(string name, string icon, Lambda childCollectionGroupConfig = null) : ChildCollectionGroupConfigBuilder

Adds a child collection group to the current collection with the given name and icon.

// Example
collectionConfig.AddChildCollectionGroup("Family", "icon-users", childCollectionGroupConfig => {
    ...
});

Umbraco stores identifiers in UDI format for most Umbraco object types.

You can read more about them in the UDI Identifiers section of the documentation.

If you want to reference an Umbraco object in your model and retrieve its Integer or Guid value, you must convert the UDI value.

Use one of UI Builder's converters - EntityIdentifierToIntTypeConverter or EntityIdentifierToGuidTypeConverter. Add it as a [TypeConverterAttribute] to your model's foreign key property.

An entity that references an Umbraco object would look like this:

You can also create a custom type converter. UI Builder will handle data persistence automatically.

Beyond listing collection entities, if you need to be able to locate specific entities within a collection then Umbraco UI Builder provides a search API.

Get started by reviewing how to define searchable properties.

Field Views allow you to customize the markup used by a field when displayed in a list view. Field Views are implemented as .NET Core View Components that are passed a single FieldViewsContext argument with information about the entity/field being rendered.

You can define a field view in one of two ways.

The simplest way to define a field view for non-complex fields is to place a view file in the /Views/Shared/Components/FieldView folder with the following markup.

When registering a basic file view you can pass the name of the view file (excluding the .cshtml file extension) to the relevant API method.

Count cards allow you to define cards directly against the configuration, providing a basic where clause to use in a count SQL statement. These work perfectly for basic data visualizations based on counts of entities in a collection.

If you need to do more than a basic count, you'll want to take a look at the documentation.

Cards allow you to display basic summaries of key information that may be useful to the editor.

Adds a card with the given name and where clause filter expression. Expression must be a boolean expression.

Adds a card with the given name + icon and where clause

Custom cards allow you to perform more complex metric calculations and are defined via a class implementing the Card base class.

When Umbraco UI Builder resolves a card it will attempt to do so from the global DI container. This means you can inject any dependencies that you require for your card to calculate its value. If there is no type defined in the DI container, Umbraco UI Builder will fall-back to manually instantiating a new instance of value mapper.

To define a card you create a class that inherits from the base class Card and configure it within the constructor like so.

The required configuration options are:

Most configuration methods in Umbraco UI Builder aim to be fluent. This means that they return a relevant config instance allowing to chain multiple methods calls together in one. For those who prefer to be a bit more verbose, many methods also accept an optional lambda expression. This allows you to pass in a delegate to perform the inner configuration of the element being defined.

Throughout the API, where a method name starts with Add then multiple configurations can be declared. Whereas if a method name starts with Set then only one instance of the configuration can be declared within the current configuration context.

The Entity Picker property editor is an Umbraco property editor that lets you select one or more entities from an Umbraco UI Builder collection.

Configuring an entity picker

To configure an entity picker you need to create a Data Type in the Umbraco backoffice. From the property editor dropdown choose 'Umbraco UI Builder Entity Picker'.

From there choose 'Section' and 'Collection' you wish to pick entities from. You can also choose an optional list view 'Data View' if there are any configured.

You can also set a minimum and maximum number of items to be able to pick if required.

With an entity picker Data Type defined, finish off the configuration by adding it to the desired Document Type definition.

Using the entity picker should be pretty familiar as it aims to mimic the content picker as closely as possible.

To pick an entity click the 'Add' link to launch the picker dialog. The dialog should present a paginated list of entities to pick from. If any searchable fields were configured for the entity type, you can perform a search by typing a search term in the search input field.

To pick your items click on the entity names and then click 'Select' in the bottom right-hand corner.

The picker should display a summary of the selected entities which can be sorted by dragging the selected entities into the desired order.

To save the value either save or save and publish the current document.

The entity picker property editor comes with a built-in . This means that whenever you retrieve the property value from Umbraco it will return the actual selected entities, even converting them to the relevant type.

Data views builders allow you to create a collection data views list dynamically at run time. By default, Umbraco UI Builder will use the hard-coded data views defined in your Umbraco UI Builder config. However, if you need to build your data views list dynamically, then this is when you'd use a data views builder.

When Umbraco UI Builder resolves a data views builder it will attempt to do so from the global DI container. This means you can inject any dependencies that you require for your builder. If there is no type defined in the DI container, Umbraco UI Builder will fall-back to manually instantiating a new instance of value mapper.

Defining a data views builder

To define a data views builder you can create a class that inherits from the base class DataViewsBuilder<TEntityType> and implements the abstract methods.

// Example
public class PersonDataViewsBuilder : DataViewsBuilder<Person>
{
    public override IEnumerable<DataViewSummary> GetDataViews()
    {
        // Generate and return a list of data views
    }

    public override Expression<Func<Person, bool>> GetDataViewWhereClause(string dataViewAlias)
    {
        // Return a where clause expression for the supplied data view alias
    }
}

The required methods are:

• GetDataViews: Returns the list of data views to choose from.

• GetDataViewWhereClause: Returns the boolean where clause expression for the given data views alias.

Setting a data views builder is controlled via the configuration.

Sets the collections data views builder which allows you to define the data views dynamically at run time.

Sets the collections data views builder which allows you to define the data views dynamically at run time.

Sets the collections data views builder which allows you to define the data views dynamically at run time.

Umbraco UI Builder can dynamically build a filter dialog choosing appropriate editor views for you based on a basic property configuration. Properties of a number or date types will become range pickers and enums. Properties with options defined will become select/checkbox lists and all other properties will become text input filters.

Defining filterable properties

Defining filterable properties is controlled via the collections configuration.

AddFilterableProperty(Lambda filterablePropertyExpression, Lambda filterConfig = null) : CollectionConfigBuilder<TEntityType>

Adds the given property to the filterable properties collection.

// Example
collectionConfig.AddFilterableProperty(p => p.FirstName, filterConfig => filterConfig 
    // ...
);

Changing the label of a filterable property

SetLabel(string label) : FilterablePropertyConfigBuilder<TEntityType, TValueType>

// Example
filterConfig.SetLabel("First Name");

Adding a description to a filterable property

SetDescription(string description) : FilterablePropertyConfigBuilder<TEntityType, TValueType>

// Example
filterConfig.SetDescription("The first name of the person");

Defining basic options for a filterable property

SetOptions(IDictionary<TValueType, string> options) : FilterablePropertyConfigBuilder<TEntityType, TValueType>

// Example
filterConfig.SetOptions(new Dictionary<string, string> {
    { "Option1", "Option One" },
    { "Option2", "Option Two" }
});

Defining options with custom compare clauses for a filterable property

AddOption(object key, string label, Lambda compareExpression) : FilterablePropertyConfigBuilder<TEntityType, TValueType>

// Example
filterConfig.AddOption("Option1", "Option One", (val) => val != "Option Two");

Configuring the mode of a filterable property

For filterable properties with options you can configure whether the options should be multiple or single choice.

SetMode(FilterMode mode) : FilterablePropertyConfigBuilder<TEntityType, TValueType>

// Example
filterConfig.SetMode(FilterMode.MultipleChoice);

Related collections add support for editing many-to-many relationships with UI Builder. These are found when multiple entities from one collection are associated with multiple entities from another. They are modeled in a database via two tables related to a junction table.

A classic example is with Students and Courses. Each course has many students, and each student takes many courses.

A representation of your collections would look like this:

A list view is a list-based view of a collection entity providing features: pagination for large collections, custom data views, searching, and bulk actions.

The list view configuration is a sub-configuration of a config builder instance and is accessed via its ListView method.

Accesses the list view config of the given collection.

Adds the given property to the list view.

Sets the heading for the list view field.

This article shows how to manually upgrade Umbraco UI Builder to run the latest version. When upgrading Umbraco UI Builder, be sure to also consult the notes to learn about potential breaking changes and common pitfalls.

To upgrade to the latest version of Umbraco UI Builder you can use:

• NuGet

• Visual Studio

This guide provides a step-by-step approach to migrating a default Konstrukt solution to Umbraco UI Builder.

Key changes

Before outlining the exact steps, there are a few key changes to be aware of.

These changes will dictate the steps to take in the process of migrating to Umbraco UI Builder.

Project, Package, and Namespace changes

In this first step, we will be replacing all existing Konstrukt dependencies with Umbraco UI Builder dependencies.

1. Remove any installed Konstrukt packages:

1. Delete the Konstrukt App_Plugins folder:

1. Install Umbraco.UIBuilder:

1. Compile your project against .NET 7.0.

Based on the outlined above update all Konstrukt references to the new Umbraco UI Builder alternatives. Ensure you update any Views/Partials that also reference these.

If all your configuration is in a single statement, it would be a case of swapping AddKonstrukt to AddUIBuilder. If you broke your configuration into multiple steps, or are using Action or Card classes, you will need to update the config builder/base classes. Those classes need to be updated to their UI Builder alternative names as detailed in .

1. Delete any obj/bin folders in your projects to ensure a clean build.

2. Recompile all projects and ensure all dependencies are restored correctly

3. Delete the existing Konstrukt license files in the umbraco\Licenses folder.

1. Run the project.

Actions are a powerful way of adding custom functionality to Umbraco UI Builder without needing to create custom UI elements. By providing an action to run, Umbraco UI Builder can automatically trigger actions from a number of UI locations.

Defining an action

To define an action create a class that inherits from the base class Action<> and configure it like below:

// Example
public class MyAction : Action<ActionResult>
{
    public override string Icon => "icon-settings";
    public override string Alias => "myaction";
    public override string Name => "My Action";
    public override bool ConfirmAction => true;

    public override ActionResult Execute(string collectionAlias, object[] entityIds)
    {
        // Perform operation here...
    }
}

The required configuration options are:

• Name: The name of the action.

• Alias: A unique alias for the action.

• Icon: An icon to display next to the name in the action button.

• Execute: The method to run against a given list of entities.

Additional optional configuration options are:

• ConfirmAction: Set whether a confirm dialog should display before performing this action.

The generic argument is a return type for the action. See below.

Actions by default will return a ActionResult but you can return other types of result by swapping the Action<> generic argument.

• ActionResult - Standard result with a boolean Success value.

• FileActionResult - Returns a file stream / bytes and triggers a download dialog.

Sometimes you may need to collect further user input before you can perform an action. To achieve this you can use the Action<> base class that accepts an additional TSetting generic argument.

By implementing this base class you are required to implement an additional Configure method which accepts a SettingsConfigBuilder<> parameter. You should use this parameter calling the builders fluent API to define the settings dialog UI and how it maps to the settings type. With the settings config builder you are able to create fieldsets and fields with the same fluent API as defined in the .

In addition to this Configure method, the Execute method will now accept an additional settings parameter of the settings type. This will be pre-populated by Umbraco UI Builder with the value entered by the user, allowing you to alter your actions behavior accordingly.

Actions are added via the configuration.

Adds an action of the given type to the collection.

Adds an action of the given type to the collection.

Adds the given action to the collection.

In this guide, you can find the necessary steps needed for a basic implementation using Umbraco UI Builder to manage a single custom database table.

Set up the database

Out of the box, Umbraco UI Builder works using PetaPoco as the persistence layer as this is what ships with Umbraco. If you prefer, it is possible to use a custom Repository. However, for getting started, it is expected that you are using this default strategy.

Start by setting up a database table for your model (you might want to populate it with some dummy data as well while learning). We’ll use the following as an example:

CREATE TABLE [Person] (
    [Id] int IDENTITY (1,1) NOT NULL,
    [Name] nvarchar(255) NOT NULL,
    [JobTitle] nvarchar(255) NOT NULL,
    [Email] nvarchar(255) NOT NULL,
    [Telephone] nvarchar(255) NOT NULL,
    [Age] int NOT NULL,
    [Avatar] nvarchar(255) NOT NULL
);

Set up your model

With the database table setup, we then need to create the associated Poco model in our project.

[TableName("Person")]
[PrimaryKey("Id")]
public class Person
{
    [PrimaryKeyColumn]
    public int Id { get; set; }
    public string Name { get; set; }
    public string JobTitle { get; set; }
    public string Email { get; set; }
    public string Telephone { get; set; }
    public int Age { get; set; }
    public string Avatar { get; set; }
}

Configure Umbraco UI Builder

With the database and model setup, we can now start to configure Umbraco UI Builder itself. The entry point for the Umbraco UI Builder configuration is via the AddUIBuilder extension method. On this method, we call on the IUmbracoBuilder instance within the Program.cs class.

For our example, we will use the following configuration:

With your configuration defined and your project compiled, there is one last step to perform before you can access your UI. And that is to give your backoffice user account permission to access the newly defined section. To do this you'll need to login to the backoffice, head to the user's section, and update the user group. There you will need to make sure that your user belongs to the allowed access.

With the permissions set, you can refresh your browser and you should now see your new section available in the site navigation.

As you can see, with little code you can start to create powerful interfaces for your custom data structures.

Context Apps in Umbraco UI Builder are analogous to Content Apps in Umbraco. They allow you to provide contextual apps that appear in the editor UI of content. From Umbraco UI Builder's perspective, defining context apps allows you to expose collections as content apps. This is where a collection has a relation to the content in question. An example could be something like blog post comments which are linked to individual blog posts. Exposing these as a content app allows them to be managed in context next to the blog post they are linked to.

Defining a context app

You can define a context app by calling one of the AddContextApp methods on a WithTreeConfigBuilder instance.

AddContextApp(string name, Lambda contextAppConfig = null) : ContextAppConfigBuilder

Adds a context app with the given name and default icon.

// Example
withTreeConfig.AddContextApp("Comments", contextAppConfig => {
    ...
});

AddContextApp(string name, string icon, Lambda contextAppConfig = null) : ContextAppConfigBuilder

Adds a context app to the Umbraco menu with the given name and icon.

// Example
withTreeConfig.AddContextApp("Comments", "icon-chat", contextAppConfig => {
    ...
});

AddContextAppBefore(string beforeAlias, string name, Lambda contextAppConfig = null) : ContextAppConfigBuilder

Adds a context app with the given name and default icon before the context app with the given alias.

Adds a context app to the Umbraco menu with the given name and icon before the context app with the given alias.

Adds a context app with the given name and default icon after the context app with the given alias.

Adds a context app to the Umbraco menu with the given name and icon after the context app with the given alias.

Sets the alias of the context app.

Optional: When adding a new context app, an alias is automatically generated from the supplied name for you. However, you can use the SetAlias method to override this if you need a specific alias.

Sets the context app icon color to the given color. Possible options are black, green, yellow, orange, blue or red.

Changing when a context app is displayed, is controlled by a delegate method which is passed a ContextAppVisibilityContext instance. This method contains a Source property which holds a reference to the source object that the content app is being displayed on (i.e., an IContent instance). It also holds a reference to a UserGroups collection of the currently logged-in user's user groups. You can use any value from those to return a boolean result which sets whether to display the context app or not.

By default, Umbraco UI Builder will pre-filter context apps to only display on the tree it is defined in. This will be combined with the SetVisibility config to decide when to display the context app.

Sets the context app visibility delegate.

Context apps can consist of one or more collections. If a context app contains multiple collections, the collection list views will be displayed in tabs within the context app.

Adds a collection to the current content app with the given names, descriptions and default icons. An ID property accessor expression is required so that Umbraco UI Builder knows which property is the ID property. A foreign key property accessor is also required so that the Umbraco UI Builder knows which property holds the Umbraco nodes UDI value. You can read more about this in the .

Adds a collection to the current context app with the given names, description and icons. An ID property accessor expression is required so that Umbraco UI Builder knows which property is the ID property. A foreign key property accessor is also required so that Umbraco UI Builder knows which property holds the Umbraco nodes UDI value. You can read more about this in the .

A dashboard is a view that is displayed at the root of a section and contains welcome information. It also includes useful tools relevant to the given section. When there are multiple dashboards to display in a section these are presented in a tabbed layout to allow you to switch between the dashboards.

Defining a dashboard

You can define a dashboard by calling one of the AddDashboard methods on either a SectionConfigBuilder or a WithSectionConfigBuilder instance.

AddDashboard(string name, Lambda dashboardConfig = null) : DashboardConfigBuilder

Adds a dashboard with the given name.

// Example
sectionConfig.AddDashboard("Team", dashboardConfig => {
    ...
});

AddDashboardBefore(string beforeAlias, string name, Lambda dashboardConfig = null) : DashboardConfigBuilder

Adds a dashboard with the given name before the dashboard with the given alias.

// Example
sectionConfig.AddDashboardBefore("contentIntro", "Team", dashboardConfig => {
    ...
});

AddDashboardAfter(string afterAlias, string name, Lambda dashboardConfig = null) : DashboardConfigBuilder

Adds a dashboard with the given name after the dashboard with the given alias.

Sets the alias of the dashboard.

Optional: When adding a new dashboard, an alias is automatically generated from the supplied name for you. However, if you need a specific alias you can use the SetAlias method to override this.

Changing when a dashboard is displayed is controlled via an inner config. Options on the inner config are ShowForUserGroup and HideForUserGroup to control the visibility of the dashboard for given user groups. You can call these config methods multiple times to add multiple role configurations.

By default, will pre-filter dashboards to display only on the section it is defined in. This will be combined with the SetVisibility config to decide when to display the dashboard.

Sets the dashboard visibility config.

Dashboards are only able to display a single collection. If you need to display multiple collections, then you need to configure multiple dashboards.

Sets the collection of the current dashboard with the given names, descriptions, and default icons. An ID property accessor expression is required so that Umbraco UI Builder knows which property is the ID property. For more information check the .

Sets the collection of the current dashboard with the given names, description and icons. An ID property accessor expression is required so that Umbraco UI Builder knows which property is the ID property. For more information check the .

A folder can appear in either a tree or as a sub folder to other folders. Folders can contain either other (sub)folders or collections.

Defining a folder

You can define a folder by calling one of the AddFolder methods on a given Tree or parent Folder config builder instance.

AddFolder(string name, Lambda folderConfig = null) : FolderConfigBuilder

Adds a folder to the current tree with the given name and a default folder icon.

// Example
treeConfig.AddFolder("Settings", folderConfig => {
    ...
});

AddFolder(string name, string icon, Lambda folderConfig = null) : FolderConfigBuilder

Adds a folder to the current tree with the given name + icon.

// Example
treeConfig.AddFolder("Settings", "icon-settings", folderConfig => {
    ...
});

Changing a folder alias

SetAlias(string alias) : FolderConfigBuilder

Sets the alias of the folder.

Optional: When creating a new folder, an alias is automatically generated from the supplied name for you. However, if you need a specific alias you can use the SetAlias method to override this.

Sets the folder icon color to the given color. The options that are possible are black, green, yellow, orange, blue or red.

Adds a sub folder to the current folder with the given name and a default folder icon.

Adds a sub folder to the current folder with the given name + icon.

Adds a collection to the current folder with the given names, descriptions, and default icons. An ID property accessor expression is required so that Umbraco UI Builder knows which property is the ID property. For more information check the .

Adds a collection to the current folder with the given names, description and icons. An ID property accessor expression is required so that Umbraco UI Builder knows which property is the ID property. For more information check the .

Umbraco UI Builder fires a number of notification events during regular operation to allow for extending of the default behaviour.

Umbraco UI Builder uses the same and so uses the same registration process. First you will need to define a notification event handler for the event you wish to handle like below:

Then register your event handler in the Program.cs file like below:

Raised when the repository Save method is called and before the entity has been persisted. The notification contains an Entity property with Before

In a number of places in the Umbraco UI Builder API, you are required to know the aliases of other elements. For example, when you are adding sections, context apps, or dashboards before/after other instances. This is basic enough when it's referencing aliases of things defined in the Umbraco UI Builder config. However, for existing Umbraco instances it can be hard to find them so below is documented a number of known aliases for different elements.

In this section, we have summarized the changes to Umbraco UI Builder released in each version. Each version is presented with a link to the UI Builder issue tracker showing a list of issues resolved in the release. We also link to the individual issues themselves from the detail.

If there are any breaking changes or other issues to be aware of when upgrading they are also noted here.

Release History

This section contains the release notes for Umbraco UI Builder 13 including all changes for this version.

(April 30th 2025)

• Added localization for tree headers and list views empty state message #115

(April 4th 2025)

• Removed global registration of UDI converters and introduced new .

• Fixed an issue for bulk actions that disabled the actions row on cancel

• Extended UdiConverter with options to convert to GUID

• Added the ActivatorUtilitiesConstructor attribute to the ImportActionEntity constructor.

• Updated licensing engine.

• Fixed issue with import entity action for Umbraco Cloud websites

• Added updates to the licensing engine.

• Added previously validated license resolver, to validate a license if a validation process was already executed successfully in the past 7 days.

• Fixed an issue caused by where clauses for filter expression and deleted property.

• Allow entity properties to be searched based on pattern: StartsWith | Contains

• Fixed an issue that did not allow a readonly field to be added multiple times to an editor

• Added support for using properties of nested objects as searchable

You can read more about this in the article.

• Fixed an issue with the UdiConverter affecting child collections

• Fixed an issue with nested objects in collection entities

• Fixed an issue with the UdiConverter causing website configuration binding to return incorrect values

• Fixed an issue where the database is getting disposed in a UIBuilder repository, causing an error when Forms tries to save the form submission after the workflow is complete .

• Allow renaming the heading of the implicit Name column by calling the SetNameProperty method overload.

You can read more about this in article.

• Use CsvHelper library with the built in ExportEntityAction.

• Update CsvHelper version dependency.

• All updates listed under 13.1.0-rc1 and 13.1.0-rc2.

• Upgrade from 13.0.3 to 13.1.0-rc1 breaks existing custom repository.

While working with a custom repository, the entity ID type converter defaulted to the newly registered UdiConverter instead of Int32Converter. With the current update, the required converter will be picked in a different order.

Umbraco UI Builder 13.1 is the first release since launch adding new features. We've focussed on improving the experience when working with related collections, addressing some additional use cases that widen the scope of the product. This includes the possibility to retrieve child collections entities or use an Umbraco entity as foreign key.

• Related Collections

This feature provides support for managing many-to-many relationships by configuring main, related and junction entities.

You can read more about this in the article.

• Retrieve Child Collections

This feature addresses a one-to-many relationship context. Having a parent collection with child sub-collections, one might need to retrieve the child collections only, without fetching the details of the parent.

You can read more about this in the article.

• Implementation of a UdiConverter

This update addresses the configuration of collections that use as foreign key a reference to an Umbraco entity. If the FK type is Integer, the persisted value defaults to 0. This is because the UDI value of the entity cannot be converted from String to Int. Based on the UDI value, we are retrieving and persisting the Id of the Umbraco entity.

A use case can be found in the .

• Dependency version update for Umbraco.Licenses

• Doesn't work after upgrading to 13.0.3

• Dependency issue when installing UIBuilder alongside Umbraco Commerce in a v13 Umbraco website

• Dependency issue when installing UIBuilder alongside uSync in a v13 Umbraco website

• Fix built-in export/import actions errors

• Update list view editorState to support integration with Contentment Data Types

• Upgraded to run again Umbraco v13 and .NET 8

• Upgraded all 3rd party dependencies

• Nullable references

You can find the release notes for Konstrukt in the .

Virtual subtrees are a powerful feature that allows you to inject an Umbraco UI Builder tree structure into another Umbraco tree at a desired location. Thus acting as child nodes to the node chosen as the injection point. With virtual subtrees it allows you to extend built in or even 3rd party package trees with additional features. An example could be developing a "loyalty point" program for your e-commerce site and injecting the related database tables into a Vendr store tree. This allows the management of the program in its most logical location.

Defining virtual SubTrees

You define a virtual subtree by calling one of the AddVirtualSubTree methods of a WithTreeConfigBuilder instance.

AddVirtualSubTree(string sectionAlias, string treeAlias, Lambda visibilityExpression, Lambda virtualSubTreeConfig = null) : VirtualSubTreeConfigBuilder

Adds a virtual subtree to the current tree with its visibility controlled via the visibility expression.

// Example
withTreeConfig.AddVirtualSubTree(ctx => ctx.Source.Id == 1056, contextAppConfig => {
    ...
});

AddVirtualSubTreeBefore(string sectionAlias, string treeAlias, Lambda visibilityExpression, Lambda matchExpression, Lambda virtualSubTreeConfig = null) : VirtualSubTreeConfigBuilder

Adds a virtual subtree to the current tree, before the tree node matches the match expression, with its visibility controlled via the visibility expression.

Adds a virtual subtree to the current tree, after the tree node matches the match expression, with its visibility controlled via the visibility expression.

Controlling where a virtual subtree is injected is done via the visibility expression passed to one of the AddVirtualSubTree methods on the root UIBuilderConfigBuilder instance. Without a visibility expression, Umbraco UI Builder would inject the virtual subtree under every node in the given tree. This expression can be used to identify the exact location where our tree should go.

To help with this, the visibility expression is passed a single VirtualSubTreeFilterContext argument with relevant contextual information. This information is about the current node being rendered, alongside a list of the current user's user groups for permission-based visibility control. It also includes access to an IServiceProvider in case you need to resolve a service to determine the correct node to inject below.

Below you can find an example of a more complex filter expression where injection is based on the Document Type of a content node:

The position of a virtual subtree within the child nodes of the injection node is controlled by using one of the AddVirtualSubTreeBefore or AddVirtualSubTreeAfter methods. These methods need to be on the root level UIBuilderConfigBuilder instance and pass a match expression used to identify the tree node to insert before/after. This expression is passed a single TreeNode argument to determine the position. It also requires a boolean return value to indicate the relevant location has been found.

Below you can find an example of positioning a subtree after a node with the alias "settings":

Virtual subtrees share the same API as the Tree config builder API including support for folders and collections. There is an exception when adding collections to a subtree where you will have an additional foreign key expression parameter to define. The foreign key expression links the entities of the collection to the parent node of the subtree. For more information check the .

Out of the box, Umbraco UI Builder supports injecting subtrees into the core content, media, members, and member group trees. It also includes 3rd party support for settings and commerce trees. In order to support additional trees to inject into, you must implement an ITreeHelper which is used to extract the required information. The tree helper consists of a tree alias for which the tree helper is. It includes methods to correctly identify the full parent path, a unique ID for a given node ID, and to resolve the actual entity ID. The entity ID should be used for the foreign key collection values.

Once you have defined a tree helper, you can register the DI container in your startup class.

Once registered any virtual subtrees registered against the given helpers tree alias will then use your tree helper to locate the required information.

Before you get to know Umbraco UI Builder, you need to become familiar with the Umbraco UI and a few of its concepts. This is because Umbraco UI Builder reuses these same concepts for constructing its UI.

1. Section A distinct area of the Umbraco backoffice.2. Tree A hierarchical structure to help organize a section. 3. Dashboard An intro screen for a section, usually with useful links for that section.

4. List View A list-based view of items in a tree node.

5. Editor The main content editing area is made up of tabs, fieldsets, and fields.

6. Context Apps A contextual section of a given editor UI.7. Tabs A tabbed container of content.

8. Menu Item A context menu item + action.

9. Bulk Action An action to perform on multiple list view items at once.

An editor is the user interface used to edit an entity and is made up of tabs and property editors.

The editor configuration is a sub-configuration of a config builder instance and is accessed via its Editor method.

Accesses the editor config of the given collection.

Adds a tab to the editor.

A slidebar is a smaller area that is displayed to the right of the main editor. The sidebar can also contain fieldsets and fields in the same way tabs can. However, it is a much more limited display area so you'll need to choose your field types carefully. The sidebar is a great location to display entity metadata.

A section is a distinct area of the Umbraco backoffice, such as content, media, etc. The section is accessed via a link in the main menu at the top of the Umbraco interface. Umbraco UI Builder allows you to define multiple sections in order to organise the management of your models into logical sections.

You can define a section by calling one of the AddSection methods on the root level UIBuilderConfigBuilder instance.

Adds a section to the Umbraco menu with the given name.

Adds a section to the Umbraco menu with the given name before the section with the given alias.