A summary dashboard appears automatically at the root of an Umbraco UI Builder section. It provides an overview of key collections within that section, enabling quick access to list views. Additionally, it allows for adding new entries to the collection, provided the collection is not set to read-only.

By summarizing important data and simplifying navigation, the summary dashboard improves content management efficiency.

Displaying a Collection on the Summary Dashboard

To display a collection on the summary dashboard, use the ShowOnSummaryDashboard() method in the collection configuration.

Configuration Example

Code Reference: ShowOnSummaryDashboard() : CollectionConfigBuilder<TEntityType>

The Entity Picker property editor allows selecting one or more entities from an Umbraco UI Builder collection.

Configuring an Entity Picker

To configure an entity picker, follow these steps:

1. Go to the Settings section in the Umbraco backoffice.

2. Create a New Data Type.

3. Select UI Builder Entity Picker from the Property Editor field.

1. Enter a Name for the picker and click Save.

2. Select the Section the collection is located in.

3. Select the Collection to pick the entities from.

4. [Optional] Select a list view Data View, if configured.

5. Enter a Minimum number of items and Maximum number of items that can be selected.

6. Click Save.

After defining the entity picker Data Type, add it to the desired Document Type.

Using an Entity Picker

The entity picker functions similarly to the content picker.

To pick an entity, follow these steps:

1. Go to the Document Type where the entity picker Data Type is added.

2. Click Add to open the picker dialog, displaying a paginated list of entities.

3. [Optional] If searchable fields are configured, use the search input field to filter results.

1. Click on the entity names.

2. Click Submit. The picker displays a summary of selected entities, which can be reordered by dragging them.

3. Click Save or Save and publish to save the changes.

Retrieving the Value of an Entity Picker

The entity picker property editor includes a built-in value converter. Retrieving the property value from Umbraco returns the selected entities, converting them to the relevant type.

// Example
foreach(var p in Model.People){
    ...
}

Umbraco UI Builder requires aliases for different elements, such as sections, context apps, and dashboards. While aliases for elements defined in the UI Builder config are straightforward, finding aliases for existing Umbraco instances can be challenging. Below is a list of known aliases for reference.

Dashboard Aliases

Content

Umbraco UI Builder is a tool for creating custom Backoffice User Interfaces (UIs) in Umbraco using a fluent API.

If you have a custom data store that you want to manage within Umbraco, you can use Umbraco UI Builder. With few 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 be set up in minutes rather than days.

This documentation is intended for developers with a basic understanding of Umbraco and C#/MVC principles.

If you are new to Umbraco UI Builder, it is recommended to start with the section. This section covers system requirements and installation instructions.

Once you have Umbraco UI Builder installed, explore the

Umbraco UI Builder strives to closely mimic the content pipeline while adhering to public and supported APIs. This ensures full compatibility with the Data Type suite for property editing. However, some features in the Umbraco Core rely on internal methods, making full support for certain functionalities challenging. Below is a list of known issues.

While Umbraco UI Builder supports persisting tag values, it currently does not write these tags to the cmsTags database table. This functionality is managed by the internal tagsRepository, which is not publicly accessible, preventing direct saving in the same manner as Umbraco Core.

Block Editors (Block List/Block Grid) are not currently supported due to casting errors between the JSON string representation and collection property.

An implementation to address this is investigated and will be scheduled for a future major release.

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

This article provides upgrade instructions for major versions of Umbraco UI Builder.

Legacy Version Upgrade Notes

For out-of-support versions, see the Legacy documentation on GitHub.

Umbraco UI Builder can be integrated into different areas of the Umbraco Backoffice. Before you start managing content, it is essential to decide which area best suits the presentation of your data. Each area offers unique features for displaying and interacting with content.

Once you have identified the most appropriate area, you can proceed with configuring it to suit your needs.

Key Areas for Integration

• Sections: The Sections area allows you to organize your content in a structured layout, enabling users to navigate different parts of the backoffice.

• Dashboards: The Dashboards area is ideal for creating custom views that provide quick access to key information and statistics.

• : Context Apps provide contextual tools and information based on the specific content a user is working with.

Selecting the correct area is essential to ensure your UI is both functional and user-friendly. Consider the nature of your content and the tasks users need to perform when deciding which area to use.

In this article, you will learn how to install Umbraco UI Builder into your Umbraco CMS implementation.

Run the following command in your web project:

For a class library without UI elements, install:

To install via Visual Studio, follow these steps:

1. Open Visual Studio and load your project.

You can configure Umbraco UI Builder either via a Composer or in the Program.cs.

A Composer is a common approach for registering and configuring services in Umbraco during application startup.

To configure Umbraco UI Builder via a Composer:

1. Create a file called UIBuilderComposer.cs in your project.

Umbraco UI Builder provides different inbuilt actions that you can use right away.

ExportEntityAction

Namespace: Umbraco.UIBuilder.Infrastructure.Configuration.Actions

Exports entity data to a Comma-Separated Values (CSV) file. It converts all properties into column headings and renders each entity's property values in rows.

ImportEntityAction

Namespace: Umbraco.UIBuilder.Infrastructure.Configuration.Actions

Imports data from a Comma-Separated Values (CSV) file. This action matches column headings with entity properties and maps row values to an entity.

Use global filters to work with a specific subset of data within a collection. These filters apply to all queries for a given collection.

Applying a Global Filter

Configure global filters in the Collections settings.

Using the SetFilter() Method

Defines a filter using a where clause expression. The expression must return a boolean value.

Method Syntax

SetFilter(Lambda whereClauseExpression) : CollectionConfigBuilder<TEntityType>

Example

Umbraco UI Builder allows encrypting properties to store sensitive information securely. When a property is marked as encrypted, its value is automatically encrypted before storage and decrypted upon retrieval.

Defining Encrypted Properties

Using the AddEncryptedProperty() Method

Encrypts the specified property. The property must be of type String. The value is encrypted before storage and decrypted when retrieved.

Method Syntax

Example

Umbraco UI Builder is a commercial product. You can use Umbraco UI Builder locally without a license. When running Umbraco UI Builder on a public domain the usage is limited to a single editable collection. To remove these restrictions, a valid license is required.

How Licensing Works

Licenses are sold per Umbraco installation. This means one license covers a single Umbraco database and its associated web project.

While the license is sold per installation, it is configured on a domain basis. This allows the Umbraco licensing server to verify that the backoffice is being accessed from an authorized environment.

Example License Configuration

When you purchase a license, you define one production domain (which includes all its subdomains) and up to two development or testing domains.

For a license configured for mysite.com, with development domains devdomain.com and devdomain2.com, the following are covered:

• Local Development: localhost, *.local, and *.test.

• Production: mysite.com and all subdomains (for example, www.mysite.com, shop.mysite.com).

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

• A single license covers the installation of Umbraco UI Builder in one 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 subdomain.

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 article explains how to manually upgrade Umbraco UI Builder to the latest version. Before upgrading Umbraco UI Builder, see the Version Specific Upgrade Notes for potential breaking changes and common pitfalls.

Get the latest version of Umbraco UI Builder

To get the latest version of Umbraco UI Builder, you can upgrade using either of the two options:

• NuGet

• Visual Studio

NuGet

• To install the latest version via NuGet:

• To specify a package version:

• After adding the package reference, restore dependencies:

1. Open Visual Studio.

2. Navigate to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution....

3. Select Umbraco.UIBuilder.

If you are using any of the following sub-packages, upgrade them as well:

A collection in Umbraco UI Builder represents a group of entities for a specific data model. It serves as the primary configuration object for defining how the collection integrates into the UI.

You can configure its list view appearance and editing options.

Get started by reviewing the basics of collection configuration.

Umbraco UI Builder includes a search API for filtering and locating specific entities within a collection. This enhances usability, especially in collections with large datasets.

Get started by reviewing how to define searchable properties.

In addition to Searching, you may need to create specific views of a collection's data. Umbraco UI Builder provides multiple filtering mechanisms to help with this.

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

Cards provide an API to display summary information in a card-based format, which is useful for displaying key metrics about a collection.

Cards can be defined in two ways:

In this article, you will find the requirements to get started with Umbraco UI Builder. Umbraco UI Builder allows you to create and manage custom UI elements for your Umbraco backoffice.

Prerequisites

• Umbraco 15+ website configured and ready to install Umbraco UI Builder.

System Requirements

To use Umbraco UI Builder, your setup must meet these minimum requirements:

• Umbraco CMS version 15+

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

Umbraco UI Builder is an add-on product for Umbraco CMS, and follows the .

Actions allow you to perform custom tasks on collections and their entities from different areas in the UI. For Example: menu actions, bulk actions, or individual table row actions.

To get started with actions, check out the basics:

This section summarizes the changes and fixes introduced in each version of Umbraco UI Builder. Each release includes a link to the , where you can find a list of resolved issues. Individual issues are also linked for more details.

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

Below are the release notes for Umbraco UI Builder, detailing all changes in this version.

• Fixed issue with section dashboard collections

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

You can read more about them in the 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]

Searchable properties allow you to define any String based properties in a model. It can be searched via Umbraco UI Builder's list view and entity picker search controls.

Both direct String properties and String properties within nested objects can be made searchable, provided the parent object is not null.

Use AddSearchableProperty to specify which properties should be included in search functionality.

Field Views allow customization of the markup used by a field when displayed in a list view. Field Views are implemented as .NET Core View Components, which are passed a FieldViewsContext argument containing information about the entity/field being rendered.

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

For field views, place a view file in the /Views/Shared/Components/FieldView folder with the following markup.

To register the view, pass the name of the view file (excluding the .cshtml file extension) to the relevant API method.

For more complex field views, create a custom view component class that can use dependency injection for any required dependencies. Use the following signature:

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, see the article.

Count cards display basic summaries of key information that may be useful to the editor.

Adds a count card with the specified name and a where clause filter expression. The filter expression must be a boolean value.

Adds a count card with the specified name, an icon, and a where clause filter expression. The filter expression must be a boolean value.

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.

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

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

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

Data views builders allow you to create a collection’s data views dynamically at runtime. By default, Umbraco UI Builder uses hard-coded data views from the configuration. However, if you need to generate data views dynamically, a data views builder is required.

When resolving a data views builder, Umbraco UI Builder first attempts to retrieve it from the global Dependency Injection (DI) container. This allows injecting required dependencies into the builder. If no type is defined in the DI container, Umbraco UI Builder falls back to manually instantiating a new instance of the value mapper.

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

The required methods are:

Umbraco UI Builder follows a fluent configuration style, allowing method chaining for concise and readable code. Alternatively, a lambda expression can be used for a more structured approach.

• Methods prefixed with Add allow multiple configurations.

• Methods prefixed with Set permit only one instance within the current configuration context.

Umbraco UI Builder provides property editors for managing data inside Umbraco content nodes.

The available property editors are:

Before diving into Umbraco UI Builder, it’s important to understand some of the fundamental concepts of the Umbraco UI. This knowledge will help you navigate and leverage the UI Builder more effectively, as it uses the same UI components to construct interfaces.

Section

A section in Umbraco is a distinct area within the backoffice where related content and functionality are grouped. For example, the Content section is where content management happens, while the Media section handles media files.

Tree

The tree represents the hierarchical structure of items within a section. It organizes content, settings, and data, for quick navigation and locating items. For example, the content tree shows the pages of a website in a nested format.

Dashboard

Each section in the Umbraco backoffice typically starts with a dashboard. This is an introductory screen for the section. It often includes useful links or shortcuts, providing an overview or quick access to the most commonly used features.

Collection

The collection displays a list of items in a tree or grid view. It provides an overview of content or data in a table format, with sortable columns and the option to filter or search through the items. This view is used when you need to work with multiple items at once.

The editor is where the main content editing occurs. It is structured using tabs, fieldsets, and fields. Tabs organize different sections of content, and fieldsets group related fields together. Each field represents a specific piece of data, such as a text box or an image upload.

Workspace Views are additional functionality that can be added to an editor. They provide extra features based on the content of the item being edited. For instance, a media Workspace View might allow you to resize or crop an image directly from the editor.

Tabs are used to organize content within the editor, allowing users to switch between different sections of a content item. For example, one tab might contain the general settings, while another contains media or advanced options.

A menu item represents an action within the context of a tree node or a list item. It is a clickable item that triggers specific tasks, such as deleting or editing an item.

Bulk actions allow you to perform an operation on multiple items in the list view at once. For example, you might use a bulk action to delete multiple content items or update their status in a single step.

In one-to-many relationships, a parent entity is associated with multiple entities from another collection. In Umbraco UI Builder, retrieving child collections from such relationships is supported through child repositories. This enables you to access related data effectively, helping to maintain a well-organized backoffice UI.

Models Representation

For a one-to-many relationship, you typically have two models: one for the parent entity and one for the child entity.

[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; }
}

In the above example, the Student model represents the parent entity. A student can have multiple associated StudentProjects.

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

    public string Name { get; set; }

    public int StudentId { get; set; }
}

The StudentProjects model represents the child entity. The StudentId is a foreign key that links each StudentProject to the Student entity, establishing the one-to-many relationship.

To retrieve data from child collections, you can use the IRepositoryFactory to create child repository instances. These repositories provide methods to fetch child entities associated with a given parent entity.

In this example:

• The StudentProjectController is using the IRepositoryFactory to create a child repository for StudentProject.

• The GetAll()method retrieves all child entities related to the given parent.

This structure allows efficient retrieval and management of child entities, providing a well-organized way to interact with related data in Umbraco's backoffice.

Custom cards enable more complex metric calculations and are defined by a class that implements the Card base class.

When Umbraco UI Builder resolves a card, it tries to do so from the global DI container. This means you can inject any dependencies required for the card's value calculation. If no type is found in the DI container, Umbraco UI Builder will fall back to manually instantiating a new instance of the value mapper.

Defining a Custom Card

To define a custom card, create a class that inherits from the base class Card and configure it in the constructor as shown below:

// Example
public class AvgPersonAgeCard : Card
{
    public override string Alias => "avgPersonAge";
    public override string Name => "Average Age";
    public override string Icon => "icon-calendar";
    public override string Color => "green";
    public override string Suffix => "yrs";
        
    public override object GetValue(object parentId = null)
    {
        // Perform value calculation logic
    }
}

Configuration Options

Adds a custom card of the specified type to the collection.

Adds a custom card of the specified type to the collection, using the Type parameter to pass the card type dynamically.

Umbraco UI Builder dynamically constructs a filter dialog by choosing appropriate editor views based on basic property configurations. Properties of numeric or date types become range pickers, enums become select/checkbox lists, and other properties are text input filters.

Defining Filterable Properties

Defining filterable properties is controlled via the Collections settings.

Using the AddFilterableProperty() Method

Adds a given property to the filterable properties collection.

Method Syntax

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

Example

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

Changing the Label of a Filterable Property

Using the SetLabel() Method

Sets the label for the filterable property.

Method Syntax

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

Example

filterConfig.SetLabel("First Name");

Adding a Description to a Filterable Property

Using the SetDescription() Method

Sets a description for the filterable property.

Method Syntax

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

Example

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

Defining Basic Options for a Filterable Property

Using the SetOptions() Method

Defines basic options for a filterable property.

Method Syntax

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

Using the AddOption() Method

Defines options with custom comparison clauses for a filterable property.

For filterable properties with options, you can configure whether the options should allow multiple or single selections.

Configures the mode of a filterable property (multiple or single choice).

UI Builder 17.1.0 adds EF Core support, converting the data access pipeline to async-first. This update impacts API controllers, services, repositories, and database extensions. Existing sync methods are now obsolete and scheduled for removal in V19.

This migration handled the following:

• Every existing sync method gets an async counterpart with an Async suffix.

• Sync methods are marked [Obsolete("Scheduled for removal in v19")].

• Sync methods are rewired to delegate to async via .ConfigureAwait(false).GetAwaiter().GetResult().

• All async methods accept an optional CancellationToken cancellationToken = default as the last parameter.

If you have a custom repository extending Repository<TEntity, TId> (or use the new EFCoreRepository<TEntity, TId>):

1. Implement all new *ImplAsync abstract methods.

2. Migrate callers from sync to async methods.

3. Pass CancellationToken through the call chain.

Value mappers in Umbraco UI Builder act as intermediaries between the editor UI and the database, allowing customization of stored field values. By default, Umbraco UI Builder saves data as it would be stored in Umbraco, but value mappers enable modifications.

When resolving a value mapper, Umbraco UI Builder first checks the global DI container. If no type is defined, it manually instantiates a new instance.

Defining a Value Mapper

To define a mapper, create a class that inherits from the base class ValueMapper and implements the EditorToModel and ModelToEditor methods.

Example

public class MyValueMapper : ValueMapper
{
    public override object EditorToModel(object input)
    {
        // Tweak the input and return mapped object
        ...
    }

    public override object ModelToEditor(object input)
    {
        // Tweak the input and return mapped object
        ...
    }    
}

Setting a Field Value Mapper

Value mappers are defined as part of a collection editor field configuration.

Using the SetValueMapper() Method

Set the value mapper for the current field.

Set the value mapper for the current field using a type reference.

Set the value mapper for the current field using an instance.

A child collection is a container for data models that are tied to a parent collection. The child collection system shares the Collections API, offering flexibility for managing and displaying related data within your backoffice UI.

By default, child collections are displayed as context apps within the parent model's editor view. If multiple child collections lead to an overcrowded context apps area, consider using the Child Collection Groups API. Using the API, you can group related child collections under a single context app, with each child collection appearing in separate tabs.

Defining a Child Collection

To define a child collection, use the AddChildCollection method on the given collection config builder instance.

Using the AddChildCollection() Method

This method adds a child collection with the specified names, description, and default icons. Both the entity ID and foreign key fields must be specified using property accessor expressions.

Method Syntax

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

Example

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

Using the AddChildCollection() Method with Custom Icons

This method adds a child collection to the current collection with the specified names, description and custom icons. Both the entity ID and foreign key fields must be specified using property accessor expressions.

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

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

Defining Data Views

Data views are defined via the Collections settings.

Using the AddDataView() Method

Creates a data view with the specified name and a where clause filter expression. The expression must return a boolean value.

Method Syntax

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

Example

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

Using the AddDataView() Method with Group

Creates a data view within a specified group, using a where clause filter expression. The expression must return a boolean value.

Method Syntax

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

Example

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

Using the AddAllDataView Method

Enables the All option for data views in the collection. The method can take an empty string, which will display the CMS localized All value, plain text, or a localized string.

A list view displays a collection entity in a list format and includes features like pagination, custom data views, searching, and bulk actions.

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

Accesses the list view configuration for the specified collection.

Adds a specified property to the list view.

Sets the heading for a field in the list view.

Sets the format expression to the field in the list view.

Umbraco UI Builder now supports EF Core. It publishes specific notifications, allowing you to modify queries before and after they are built.

These are the EF Core equivalents of the NPoco SqlQueryBuildingNotification and SqlQueryBuiltNotification.

Umbraco UI Builder follows the for event registration.

To define a notification event handler for the target event, please check the section.

Triggers when the default EF Core repository is preparing a query. The notification provides access to the IQueryable

Dashboards in Umbraco UI Builder provide an intuitive way to present important information and tools at the root of a section within the Umbraco backoffice. They serve as a starting point for users, offering quick access to relevant data, insights, or actions. Dashboards can be customized, reordered, and configured to display for specific user groups, making them a flexible tool for enhancing the backoffice experience. When multiple dashboards are available in a section, they appear in a tabbed layout for navigation.

Defining a Dashboard

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

Using the AddDashboard() Method

Adds a dashboard with the specified name.

Method Syntax

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

Example

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

Using the AddDashboardBefore() Method

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

Method Syntax

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

Example

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

Using the AddDashboardAfter() Method

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

Sets the alias of the dashboard. By default, an alias is automatically generated based on the supplied name. If a specific alias is required, the SetAlias method can be used to override the default.

Dashboard visibility can be controlled using ShowForUserGroup and HideForUserGroup, which specify which user groups can see the dashboard. These settings can be applied multiple times for different user roles.

By default, dashboards are pre-filtered to display only in their defined section. This filtering is combined with the SetVisibility method to control when a dashboard appears.

Defines visibility rules for the dashboard.

A dashboard can display only one collection. To display multiple collections, multiple dashboards must be configured.

Assigns a collection to the dashboard with the specified names, descriptions, and default icons. The ID property must be defined. For more details, see the article.

Assigns a collection to the dashboard with the specified names, descriptions, and custom icons. The ID property must be defined. For more details, see the article.

Folders help organize trees in Umbraco UI Builder, allowing you to structure content with nested folders and collections. A folder can exist within a tree or as a sub-folder within another folder. Folders can contain either sub-folders or Collections.

Defining a Folder

To define a folder, use one of the AddFolder methods on a Tree or parent Folder config builder instance.

Using the AddFolder() Method

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

Method Syntax

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

Example

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

Using the AddFolder() Method with Custom Icon

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

Method Syntax

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

Example

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

Changing a Folder Alias

When creating a new folder, an alias is automatically generated. However, if you need a specific alias, you can use the SetAlias method to override it.

Sets a custom alias for a folder.

Sets the folder icon color to the given color. The available colors are: black, green, yellow, orange, blue, or red.

Adds a sub-folder inside the current folder with a specified name and a default folder icon.

Adds a sub folder to the current folder with a specified name and custom icon.

Adds a collection to the current folder with the given names, descriptions, and default icons. The ID property must be defined. For more details, see the article.

Adds a collection to the current folder with the given names, description and icons. The ID property must be defined. For more details, see the article.

The localization context enables developers to use multilingual collection names and descriptions in fluent configurations. It also supports translations for actions, context apps, dashboards, sections, and trees.

To enable localization, prefix the input string with the # character.

Upon character identification in the fluent configuration, the localization context will attempt to lookup a matching localized string using two services available. If no matching record is found, it will default to the provided string value.

Supported areas:

• Collections - Name and Description properties.

• Data Views - only if the key is in a localization resource, not in the translation dictionary (e.g. ).

• Collection filters - Label and Description properties.

• Cards

• Editor fields - Label and Description field properties.

• Fieldsets names

• Actions names

• Context Apps names

• Dashboards names

• Sections names

The localization context uses two abstractions to provide localization options.

The first uses the Umbraco translations dictionary to retrieve a value based on a provided key.

The second uses the CMS ILocalizedTextService to retrieve a value based on area and alias. These values are supplied in the collection's fluent configuration, separated by an underscore _ from the localization resources.

For a Students collection, use the following fluent configuration:

Alternatively, you can use the lowercase version:

Define the translation in your localization dictionary file:

For a custom section, use the following configuration:

When the implemented localization does not cover a specific area, you can update it directly in the fluent configuration by using the LocalizationContext.

For example, this custom data view:

Virtual subtrees inject an Umbraco UI Builder tree structure into another Umbraco tree at a specified location, acting as child nodes of the injection point. They extend built-in or third-party package trees with additional features. For example a "loyalty points" program for an e-commerce site can inject related database tables into a Commerce store tree, making management more intuitive.

Defining Virtual SubTrees

Use the AddVirtualSubTree methods of a WithTreeConfigBuilder instance to define a virtual subtree.

Using the AddVirtualSubTree() Method

Adds a virtual subtree to the current tree with visibility controlled by the specified expression.

Method Syntax

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

Example

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

Using the AddVirtualSubTreeBefore() Method

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

Method Syntax

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

Example

withTreeConfig.AddVirtualSubTreeBefore(ctx => ctx.Source.Id == 1056, treeNode => treeNode.Name == "Settings", contextAppConfig => {
    ...
});

Using the AddVirtualSubTreeAfter() Method

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

Control the injection location by passing a visibility expression to the AddVirtualSubTree methods on the root UIBuilderConfigBuilder instance. Without a visibility expression, the subtree appears under every node in the target tree. This expression can be used to identify the exact location where the tree should go.

The visibility expression receives a VirtualSubTreeFilterContext argument with relevant contextual information. The information includes 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 for dependency resolution.

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. The match expression identifies the node for insertion. This expression passes 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 use 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, see the article.

Out of the box, Umbraco UI Builder supports injecting subtrees into the core content, media, members, and member group trees. It also includes third-party support for settings and commerce trees. To inject into additional trees, implement an ITreeHelper to extract necessary data. 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, register the DI container in your startup class.

Once registered, any virtual subtree assigned to the helper’s tree alias will use it to locate required data.

By default, actions are hidden in the UI. You must define when and where an action should appear. This can be done either at the action definition level or when registering it in the collection config.

Controlling Default Action Visibility

To define the default visibility of an action, override the IsVisible method of the Action<> base class.

// Example
public class MyAction : Action<ActionResult>
{
    ...
    public override bool IsVisible(ActionVisibilityContext ctx)
    {
        return ctx.ActionType == ActionType.Bulk 
            || ctx.ActionType == ActionType.Row;
    }
    ...
}

The IsVisible method receives an ActionVisibilityContext. You can use this context to decide whether the action should be displayed. Return true to show it, or false to hide it. For more information, see the Action visibility context section below.

You can override an action's visibility in the settings.

Adds an action of the given type to the collection with the specified visibility.

Adds an action of the given type to the collection by specifying the action type dynamically using Type instead of a generic type.

Adds the already defined action instance to the collection with the specified visibility.

When controlling the visibility of an action, you will receive an ActionVisibilityContext object. This context allows you to decide whether to show the action. The context contains two key pieces of information for this decision.

The ActionType property is an enum property that defines which area of the UI wants to access the action. This property helps determine where the action is displayed.

The ContainerMenu action type displays the action in both the collection tree and its list view actions menu.

The EntityMenu action type shows the action in the collection editor UI's actions menu.

The Bulk action type displays the action in the collection list view bulk actions menu.

The Row action type shows the action in the collection list view action row menu.

The Save action type displays the action as a sub-button in the entity editor’s save button. All Save actions trigger a save before executing. Their labels are prefixed with Save & [Action Name].

The UserGroups collection contains a list of IReadOnlyUserGroup objects for the current logged-in backoffice user. This allows you to control action visibility for members of specific user groups.

Actions allow you to add custom functionality to Umbraco UI Builder without creating custom UI elements. By providing an action to run, Umbraco UI Builder can trigger actions from different UI locations.

Defining an Action

To define an action, create a class that inherits from the base class Action<> and configure it as shown 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...
    }
}

Configuration Options

The generic argument specifies the return type for the action. For more details, see the section below.

{% hint style="info" %} You can use dependency injection to inject any services required for your specific task. It's recommended to inject Lazy<YourService> implementations of the required services to ensure they are resolved only when needed. {% endhint %}

By default, actions return an ActionResult, but you can return other types by changing the Action<> generic argument.

• ActionResult - Standard result with a boolean Success value.

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

Sometimes, you need to collect user input before performing an action. You can achieve this by using the Action<> base class with an additional TSetting generic argument.

By implementing this base class, you must also implement the Configure method which accepts a SettingsConfigBuilder<> parameter. Use this builder to define the settings dialog UI and how it maps to the settings type. You can create fieldsets and fields with the same fluent API as in the section.

Additionally, the Execute method now accepts an extra settings parameter, which Umbraco UI Builder will pre-populate with the user-entered values. You can adjust the action's behavior based on this data.

Actions are added via the settings.

Adds an action of the specified type to the collection.

Adds an action of the specified type to the collection.

Adds the given action to the collection.

This guide walks you through a basic implementation of Umbraco UI Builder to manage a custom database table.

Umbraco UI Builder uses PetaPoco as its default persistence layer.

In this section, you will create a Person table to store data.

To create a Person table, run the following script in SQL Server Management Studio (SSMS).

This script creates a table for storing people’s details. You may want to populate it with some dummy data for testing.

With the database table created, define the Person

This guide walks you through migrating a default Konstrukt solution to Umbraco UI Builder.

Before starting, review these key changes that impact the migration process.