Umbraco Forms supports Themes, allowing forms to be customized in a much simpler manner.

Creating a Theme

To create a theme, you need to create a folder at /Views/Partials/Forms/Themes/. The name of the folder is the name of theme that will be visible in the backoffice when choosing it.

Copy the explicit files you wish to override in your theme, it may be a single file or all files from the default theme folder. Make the necessary changes you desire to CSS class names, markup etc.

Obtaining the Default Theme Files

For Umbraco 9 and previous, it's straightforward to copy the files you need from the default theme folder. We highly recommend that you never customize any files found in the default themes folder. There is a risk that any customizations to these files will be lost with any future upgrades you do to Umbraco Forms. Umbraco 10+ distributes these files as part of a Razor Class Library, so you won't find them on disk. Instead you should download the appropriate zip file for your Forms version and extract the ones you need.

You can obtain the latest version of the Forms default theme from the following links:

You should use the theme available for the highest version that's less or equal to the version of Forms you have installed.

If adding or amending client-side scripts, you need to copy the Script.cshtml file from the default themes folder. In your copy, amend the .js references to reference your own script files.

Umbraco Forms provides it's built-in themes as part of a Razor Class Library for ease of distribution. This can be useful for custom themes, particularly those used in multiple solutions or released as an Umbraco package.

It is also possible to do this for custom themes.

1. Create a new Razor Class Library project to hold the theme.

2. Create the necessary Partial Views for your theme within Views\Partials\Forms\Themes\<my-custom-theme>.

3. Provide the names of the files in your theme via an implementation of ITheme.

• For example, if only overriding a single file, your class would look like the code snippet below:

1. Register the themes you want to use via a composer:

Your theme will now be available in the Theme Picker and the partial view files will be used when rendering forms.

Email templates provided for the send email workflow can be provided in a Razor Class Library similar to the Theme files.

The partial view will be created in Views\Partials\Forms\Emails.

It's made available via an implementation of IEmailTemplate:

And registered with:

Removing the Default Email Template

If providing custom email templates, you may want to remove the one provided with Forms. You can do that via the same EmailTemplates collection.

When rendering a form in a view file, you can specify which theme to use with the form.

Learn more about how to render a form with a theme in the article.

When using a theme, Umbraco Forms will try to use a view from the theme folder, but then fallback to the same view in the default theme folder if it can't be found. This allows you to create a theme by only modifying the files necessary to make your customizations.

Files which can be overridden:

• Render.cshtml (overrides the entire form - usually not needed)

• Form.cshtml (overrides the generation of the fields on the current page)

• Script.cshtml (overrides the way files are included with the form)

• ScrollToFormScript.cshtml (overrides the script used to scroll to the form after submission)

Sets the primary form theme stylesheet path. This overrides an already assigned stylesheet and will be rendered out when inserting the form into the page

Add a JavaScript file path to include on form render

Adds a class to the form field HTML element of a given type. If no type is given, it will add the class to all fields

Retrieves all classes for a given field type, used when rendering form fieldtype partial views

Adds a class to the div element wrapping around form fields of a given type. If no type is given, it will add the class to all fields

Retrieves all wrapper classes for a given field type, used when rendering form fields. This class wraps both label, help-text and the field itself in the default view

Umbraco Forms will register events for workflow operations that you can use with Umbraco webhooks.

Workflows are operations that you can associate with form submission, approval, or rejection actions. You can use these where you need to notify external systems of the success or failure of a workflow.

On the Umbraco Settings > Advanced > Webhooks dashboard, you can configure webhooks to respond to workflows.

You can amend the registration of workflow events in code.

To remove the webhooks that are added by default you can use a composer as follows:

using Umbraco.Cms.Core.Composing;
using Umbraco.Forms.Core.Extensions;

internal sealed class TestComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.WebhookEvents().AddForms(formsBuilder => formsBuilder.RemoveDefault());
}

You can view the System information of the form in the Info tab.

To access the Form Information:

1. Go to the Forms section.

2. Open a Form you wish to customize.

3. Click Info in the top-right corner of the screen.

The "General" panel displays system information about the form. The date the form was created and last updated are shown. Also available are the integer and GUID identifiers that are useful when referring to the form in code.

Information about which pages a form is hosted on is tracked by Umbraco every time a content item is saved.

The list of pages where the form is hosted is shown in this section.

The Umbraco Forms backoffice is built on the Umbraco CMS extension system. You extend it by registering manifests, each with a type that tells Umbraco what kind of extension it is.

This article lists the extension points that Forms adds on top of the CMS. Use it as a map: each point links to the detailed guidance for that scenario.

Before you start, install and configure the @umbraco-forms/backoffice package as described in the Extending article.

Overview

Server-side providers, such as field types and workflow types, are registered in C#. These are covered in .

Forms uses the same registration mechanism as the CMS. You declare your manifests and register them through your package's entry point.

For the full setup, including the umbraco-package.json manifest that points to this entry, see the article.

Field types and workflow types expose their settings through a standard CMS propertyEditorUi. You register a property editor UI and reference its alias from the type's EditView or setting definition.

A common requirement is to read the open form from a settings editor. For example, to list the form's fields in a mapping grid. Consume the Form Workspace Context to do this.

For full examples of field and setting editors, see and .

A field preview renders a representation of a field type in the form designer. The preview receives the field's settings and prevalues. Extend FormsFieldPreviewBaseElement and read settings with getSettingValue(alias).

Register the preview with a formsFieldPreview manifest:

A setting value converter converts a setting value between the format used by the editor and the format stored with the form. Implement FormsSettingValueConverterApi and tie it to a property editor UI through propertyEditorUiAlias.

For more on settings and converters, see .

There are some default prevalue source types that can be used. In this article, we will give a quick overview of them:

Get values from textfile

Upload a textfile that contains the prevalues. Each prevalue should have its own line in the file. Once the file has been uploaded, you can find it in ~/wwwroot/App_Data/UmbracoForms/Data/PreValueTextFiles/{GUID} where the {GUID}is replaced with the pre-value ID.

Umbraco Documents

Allows you to use content nodes from a specific source as prevalues. Configure the following options in the Details section:

• Define the root node by either:

  • Selecting the type of item the picker should target such as Content, Media, or Members, or

  • Specifying a dynamic root.

• Enable Use current page as root instead of choosing a specific root node. Preview is not available when this setting is enabled.

• Choose a specific Document type, if the selected root node contains a different Document Type.

• Select the Value field to define the value stored for the prevalue.

• Select the Caption field to define the label shown in the list.

• Enable List all Descendants of the selected root node to include all child nodes beneath the root.

• Select Order by from the drop-down list to display how the prevalue list is sorted.

• Select your preferred Cache option for caching the list of prevalues when rendering in a form.

Connect to a OleDB compatible database table and construct a prevalue source from it. Once selected, it will be editable from the Forms interface.

Configure the following options in the Details section:

• Connection string (either choose one from your web.config or add another from a textfield).

• Connection String from configuration

• Table Name

• Key Column

Choose an Umbraco Data Type to use its configured prevalue collection.

In the example below, the prevalue collection from a Data Type called Home - Font - Radio button is used:

Umbraco Forms includes built-in analytics that provide insight into how your forms are performing. You can view submission trends over time, monitor workflow success rates, and identify which pages are driving submissions.

Permissions

To view form analytics, you need:

• Access to the Forms section in the backoffice.

• The View Entries permission for the form.

Users will only see analytics for forms they have permission to manage.

Accessing Analytics

There are two ways to access form analytics in the backoffice.

In the Forms section, click the Analytics menu item in the sidebar. This opens the analytics overview where you can browse data across all your forms.

You can navigate directly to analytics for a specific form:

1. Go to the Forms section.

2. Right-click on a form or open its action menu.

3. Select View Analytics.

This opens the Analytics tab on the form workspace, showing analytics data for that form only.

The analytics view provides controls to adjust the data displayed.

Use the date range picker to select the time period for the analytics data. You can choose from preset ranges such as Last 7 days or Last 30 days, or set a custom date range. You can also enable a comparison date range to compare the current period against a previous one.

Use the Group by control to change how the data is aggregated in the time-series charts:

• Day — shows data points for each day in the selected range.

• Week — groups data by week.

• Month — groups data by month.

The overview table lists all forms you have access to with summary statistics for the selected date range. This includes entry counts, workflow counts, workflow errors, source pages, and unique members.

Click a form name to navigate to its detailed analytics view.

The overview also shows a Unique members total across all your forms. See .

When viewing analytics for a specific form, the view displays four widgets providing different perspectives on form performance.

A time-series chart showing the number of form submissions and failed workflows over the selected date range.

A chart showing the distribution of form submissions across the 24 hours of the day. This helps identify peak submission times and can inform decisions about when to schedule maintenance or review submissions.

A table listing each workflow attached to the form. It shows the number of times each workflow was triggered, succeeded, and failed. Use this to monitor the health of your form processing workflows.

A time-series chart showing form submissions broken down by the page where the form was submitted. This is useful when the same form is placed on multiple pages across your site, as it shows which pages are driving the most submissions.

Below the chart, a table lists each source page with its name, URL, and entry count.

The Unique members metric counts the distinct logged-in members who submitted a form in the selected date range. It appears on the analytics overview as a total across all your forms, and on each form's detailed view.

A member who submits the same form more than once is counted once. Anonymous submissions are never counted. Entries from members who have since been deleted are still counted.

The metric shows 0 when there are no member submissions in the range. It is never blank.

Analytics data is pre-aggregated by a background process that runs daily. This means the analytics views load quickly even for forms with a large number of submissions.

When forms are first installed or upgraded to a version that includes analytics, the background process will aggregate historical submission data. This may take some time depending on the volume of existing records.

The member editor in the Members section includes a Forms tab. The tab lists the forms a member has submitted and lets you open their entries without leaving the Members section.

The Forms tab

Open a member in the Members section. The Forms tab appears alongside the member's other tabs.

The tab is hidden in two cases:

• The member is new and has not been saved. A new member has no entries.

• You do not have access to the Forms section.

The tab lists every form the member has at least one entry for, with the number of entries per form.

Forms the member has not submitted are not listed. Forms you do not have permission to access are not listed either.

When the member has no entries for any form, the tab shows a standard empty state.

From the list you can drill into the member's activity:

• Select a form name to open the form's details in the Forms section.

• Select the entry count, or View entries for this form, to open the member's entries for that form.

• Select an entry to open the entry details.

The entries and entry details reuse the same views as , filtered to the current member.

The Forms tab respects Forms permissions.

• The tab is hidden when you do not have access to the Forms section.

• Forms you cannot access are filtered out of the list on the server, so they are never shown or navigable.

In Umbraco Forms, reCAPTCHA Enterprise comes out of the box.

reCAPTCHA Enterprise allows you to verify if an interaction is legitimate without any user interaction.

Follow these steps to enable reCAPTCHA Enterprise in Umbraco Forms:

1. Go to the Forms section in the backoffice.

2. Find the form that should have ReCAPTCHA Enterprise enabled.

By default, a single workflow is added when a new form is created. This workflow will send a copy of the form to the email address of the current backoffice user.

A single "data consent" field will also be added unless it has been disabled via configuration.

It's possible to amend this behavior and change it to fit your needs.

Implementing a Custom Behavior

Two interfaces are used to abstract the logic for setting default fields and workflows for a form. They are IApplyDefaultFieldsBehavior and IApplyDefaultWorkflowsBehavior respectively.

The default behaviors are defined using built-in, internal classes that implement this interface.

You can create your own implementation of these interfaces.

Example - Providing a Custom Apply Workflows Behavior

An illustrative example, adding a custom workflow that writes to the log, is shown below.

Firstly, the custom workflow:

Secondly, the custom implementation of IApplyDefaultWorkflowsBehavior:

Finally, to register the custom implementation in place of the default one:

When adding a default workflow in code, it's possible to make it mandatory, which will prevent editors from removing it from a form.

You can see this in the example above, where the IsMandatory property of the created FormWorkflowWithTypeSettings instance is set to true.

The following class shows the default implementation provided with Forms. You can copy this and customize it to your needs.

Again, you will need to register your custom class, for example, in a composer with:

Install Umbraco Forms following either of the two guides:

• , or

• .

An Umbraco CMS website set up locally or in a development environment.

To install Umbraco Forms using NuGet in Visual Studio, follow these steps:

When working with the Block List editor, the editor experience is enhanced by defining a label for the appearance of the Block.

These labels can use Umbraco Flavored Markdown (UFM).

An option is available to display a form's name - umbFormName.

It should be rendered as follows, with a reference to the property alias on the block element that uses a form picker.

{umbFormName: <property-alias>}

If you add a reference to a property containing a form to the block's label, it will render with the form's Id.

For example, assuming a property containing a picked form with an alias of contactForm:

{=contactForm}

By using the markdown as follows, the form's name will be displayed instead.

{umbFormName: contactForm}

When forms are created, editors will want to add them to pages in Umbraco. To do this they need a Document Type with a property that uses a Data Type based on a Form Picker property editor.

Umbraco Forms provides three variations of a form picker.

Most commonly used is Form Picker (single). This will allow the editor to select a single form for display on page.

Rarely but feasibly, you will have a requirement to present multiple forms on a page. Should this be appropriate, you can use Form Picker (multiple).

Finally you can provide further flexibility for the editor to select not only a form but also the theme and redirect as well. For this you will use the Form Details Picker.

Configuring the Data Type

Each property editor allows you to restrict the forms that can be chosen with the Data Type. You do this by setting either or both of the list of "Allowed folders" or "Allowed forms".

The "Form Details Picker" also allows you to select whether a theme or redirect selection is available.

The type of a property based on the Form Picker presented in a Razor class library is as follows:

Each reference to a form supports expansion via the Umbraco Content Delivery API, as described .

This documentation platform covers only major versions of Umbraco Forms. If you are using an older version of Umbraco Forms, you will need to go elsewhere.

This article walks you through creating a basic form in Umbraco Forms and adding it to your site. You’ll learn how to access the Forms section, build a form with pages, groups, and fields, and publish it on a content page.

You can manage the Forms in the Forms section of the Umbraco backoffice. You need access to the section to see it.

If you cannot see the Forms section, ask an Administrator to grant you access from the Users section.

To create a Form, follow these steps:

1. Go to the Forms section in the backoffice.

With Umbraco Forms, it is possible to customize the output markup of a Form, which means you have complete control over what Forms will display.

The razor macro uses some razor views to output the Form:

• 1 view for each fieldtype

• 1 view for the scripts

• 1 view for the rest of the Form

Deleting a form or a folder moves it to the recycle bin. Nothing is removed from the database until you delete it from the bin.

The Recycle Bin sits below the form tree in the Forms section.

1. Go to the Forms section.

2. Select the form or folder you want to delete.

Umbraco Forms is a commercial product. You can run Umbraco Forms unrestricted locally without the need for a license. Running Umbraco Forms in the public domain will require a valid license.

Version 16 supports both the one-off purchase and (in 16.1+) subscription license.

How does it work?

Licenses are sold per domain and will also work on all subdomains. With every license, you will be able to configure two development/testing domains.

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

The license will cover the following domains:

• localhost

• *.mysite.com

• www.mysite.com

• mysite.com.local

• devdomain.com

• www.devdomain.com

• devdomain2.com

• www.devdomain2.com

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

• A single license covers the installation of Umbraco Forms in 1 production domain, as well as in 2 development domains.

• The production domain includes all subdomains (e.g. *.mysite.com), as well as the .local extension (e.g. mysite.com.local).

• The development domains work with or without the www

You can look at the pricing, features, and purchase the license on the page.

Once you've purchased your subscription 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.Forms.

You can request to replace or reconfigure domains on a subscription-based license free of charge. This includes replacing temporary hostnames when your site goes live.

The free changes apply as long as you stay within the included allowance:

• 1 production domain

• 2 development/testing domains

To update your domains, visit the page or contact .

If you need more domains than your license includes, you can purchase additional domains. For more information, see .

An additional domain is an add-on for an existing license. It extends coverage to a second (or further) production environment on the same Umbraco installation.

Each additional domain follows the same coverage rules as the primary license domain. It includes all subdomains and the .local extension for the live domain, plus two development/testing domains with and without the www subdomain.

Additional domains are intended for cases where multiple distinct domains point at the same installation. An example could be when running separate regional or brand sites side by side. Because a single license covers only one production domain, each extra domain requires its own add-on.

Adding an additional domain to your license is a permanent add-on to the license; refunds are not available for additional domain purchases.

If you need to add additional domains to your license, with your request and they will manage this process.

The algorithm used to decrypt Forms licenses is not supported on locked down FIPS compliant environments, such as those used in the defense industry.

If you are in this situation and unable to resolve it via configuration of the environment, reach out to Umbraco Support.

We have the possibility of generating and providing Forms licenses using alternate algorithms.

Apply the following configuration with the appropriate algorithm - DES (the default), TripleDES, or AES:

You can link a form field to a property on your site's members. When a logged-in member opens the form, Umbraco pre-fills the field with the value it already holds for that member. This saves the member from re-entering data you already have.

When you edit a field, the field editor shows a Member pane alongside the other settings.

The pane has two controls:

• Member property — the member property to link the field to, or None to leave the field unlinked.

Umbraco Forms is a tool that lets you build forms of all shapes and sizes and put them on your Umbraco websites. Build forms using a long list of elements like multiple choice, dropdowns, text areas and checkboxes. Choose between a series of different workflows and control what happens once a form has been submitted.

or sign up for an project where Umbraco Forms is part of the package.

/*
 Applies recommended primary keys, foreign keys and indexes to Umbraco Forms tables relating to "forms in the database" (i.e.
 when configuration key StoreUmbracoFormsInDb = true).
 This replicates for SQL Server the migration AddFormKeysAndIndexes.
 */

-- Adds unique constraint to UFForms.
ALTER TABLE dbo.UFForms
ADD CONSTRAINT UK_UFForms_Key UNIQUE NONCLUSTERED 
(
	[Key] ASC
) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

-- Adds unique constraint to UFDataSource.
ALTER TABLE dbo.UFDataSource
ADD CONSTRAINT UK_UFDataSource_Key UNIQUE NONCLUSTERED 
(
	[Key] ASC
) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

-- Adds unique constraint to UFPrevalueSource.
ALTER TABLE dbo.UFPrevalueSource
ADD CONSTRAINT UK_UFPrevalueSource_Key UNIQUE NONCLUSTERED 
(
	[Key] ASC
) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

-- Adds unique constraint to UFWorkflows.
ALTER TABLE dbo.UFWorkflows
ADD CONSTRAINT UK_UFWorkflows_Key UNIQUE NONCLUSTERED 
(
	[Key] ASC
) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

-- Adds index on join field in UFWorkflows.
CREATE NONCLUSTERED INDEX IX_UFWorkflows_FormId ON dbo.UFWorkflows
(
	FormId ASC
) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, SORT_IN_TEMPDB = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

Reverting the application of keys and indexes

In Umbraco Forms, reCAPTCHA V3 comes out of the box.

reCAPTCHA v3 allows you to verify if an interaction is legitimate without any user interaction.

Enabling reCAPTCHA V3

Follow these steps to enable reCAPTCHA V3 in Umbraco Forms:

1. Go to the Forms section in the backoffice.

2. Find the form that should have ReCAPTCHA v3 enabled.

3. Add a new question and select ReCAPTCHA v3 with Score as its answer type.

4. Make sure the field is set as Mandatory.

5. Configure ReCAPTCHA settings in the appSettings.json file to include public and private keys:

You can create your keys by logging into your .

Refer to to see additional options that can be set in the appSettings.json for reCAPTCHA v3.

Umbraco Forms comes with a bunch of default Field Types, also known as Answer Types. You can choose from different field types when adding new fields to your Forms.

By default, the following Field Types are available:

• Short Answer: A textbox allows up to 250 characters.
• Long Answer: A bigger text field that allows multiline text and more than 250 characters.

This builds on the "" chapter

Umbraco Forms can be used to replace placeholders within form elements with values from different sources. Sources include the HTTP request or the Umbraco page where the form is hosted.

These values can be formatted using .

Filter functions for common operations such as truncating a string or formatting a date or number are provided. It's also possible to create custom ones in code.

To create a custom format function, create a class that implements IParsedPlaceholderFormatter.

The FunctionName property provides the name of the function that will be used within the form's magic string.

The FormatValue

There are two options available for rendering a form.

To display a form in your view, you can make a call to a view component. You can use a forms GUID directly or add a form dynamically by referencing a form selected via a Forms Picker.

When selecting a theme, it can be added directly as a string or dynamically by referencing a theme picked via a Theme Picker.

Umbraco Forms records each change made to a form. The record is kept for the life of the form and is shown in the backoffice.

1. Go to the Forms section.

2. Select the form you want to view.

3. Go to the Info tab.

The date picker uses a front-end library called to display a UI to pick dates.

Pikaday date picker can be localized based on the page the Form is rendered on.

The date picker displays the picked date in the required locale. Using JavaScript, a hidden field is updated with a standard date format to send to the server for storing record submissions. This avoids the locale mixing up the dates.

To achieve localized date, a Razor partial view is included at /Views/Partials/Forms/Themes/default/DatePicker.cshtml.

The DatePicker.cshtml includes the moment-with-locales.min.js library to help with the date locale formatting and the appropriate changes to Pikaday to support the locales. If you wish to use a different DatePicker component, edit the DatePicker.cshtml file as per your needs.

The Date picker has

Umbraco Forms comes with some built-in fields however it is possible to exclude/remove them if necessary. There might some use cases where you have no use for file upload and don't want editors using them. Or perhaps you want to remove a field to replace it with one with enhanced functionality that you build yourself.

Example

The following class shows how to exclude built-in field types using a custom composer. The Password, Recaptcha2 and RichText field types (or "answers") will no longer be available for selection when creating a form in the backoffice.

using Umbraco.Cms.Core.Composing;
using Umbraco.Forms.Core.Providers.Extensions;
using Umbraco.Forms.Core.Providers.FieldTypes;

namespace MyNamespace
{
    public class MyFormFieldsComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.FormsFields()
              .Exclude<Password>()
              .Exclude<Recaptcha2>()
              .Exclude<RichText>();
        }
    }
}

When using Umbraco UI Builder alongside Umbraco Forms, you can use a configured UI Builder repository as a prevalue source.

To do this, you will need to create a custom FieldPreValueSourceType source that uses UI Builder's SectionConfiguration property editor. Once configured, you can select a repository and fetch the prevalues from there.

Example

The following class shows how to create a UIBuilderRepository prevalue source type.

using System.Text.Json;
using System.Text.Json.Serialization;
using Umbraco.Cms.Core.Models;
using Umbraco.Forms.Core;
using Umbraco.Forms.Core.Attributes;
using Umbraco.Forms.Core.Models;
using Umbraco.UIBuilder.Configuration;
using Umbraco.UIBuilder.Services;

namespace MyFormsExtensions
{
    public class UIBuilderRepository : FieldPreValueSourceType
    {
        private readonly UIBuilderConfig _config;
        private readonly EntityService _entityService;

        public UIBuilderRepository(
            UIBuilderConfig config,
            EntityService entityService)
        {
            Id = new Guid("ED56A31B-56FD-41EA-9D21-755750879D13");
            Name = "UI Builder Repository";
            Alias = "uiBuilderRepository";
            Description = "Use a UI Builder repository as a prevalue source.";
            Icon = "icon-file-cabinet";

            _config = config;
            _entityService = entityService;
        }

        [Setting("Source", Description = "Select the source section, collection and data view", View = "UiBuilder.PropertyEditorUi.EntityPicker.SectionConfiguration", IsMandatory = true, DisplayOrder = 10)]
        public virtual string Source { get; set; } = string.Empty;

        public override Task<List<PreValue>> GetPreValuesAsync(Field? field, Form? form)
        {
            var result = new List<PreValue>();

            UIBuilderSectionConfiguration? configuration = ParseSourceConfiguration();
            if (configuration != null)
            {
                if (!string.IsNullOrEmpty(configuration.Collection))
                {
                    CollectionConfig collectionConfig = _config.Collections[configuration.Collection];
                    IEnumerable<object> entities;

                    if (string.IsNullOrEmpty(configuration.DataView))
                    {
                        entities = _entityService.GetAllEntities(collectionConfig);
                    }
                    else
                    {
                        var allEntities = new List<object>();
                        const int pageSize = 100;
                        int pageNumber = 1;
                        long totalPages = 0;

                        while (pageNumber == 1 || pageNumber <= totalPages)
                        {
                            PagedResult<object> pagedResult = _entityService.FindEntities(
                                collectionConfig,
                                pageNumber: pageNumber,
                                pageSize: pageSize,
                                dataViewAlias: configuration.DataView);

                            if (pagedResult.Items != null)
                            {
                                allEntities.AddRange(pagedResult.Items);
                            }

                            if (pageNumber == 1)
                            {
                                totalPages = pagedResult.TotalPages;
                            }

                            pageNumber++;
                        }

                        entities = allEntities;
                    }

                    foreach (var entity in entities)
                    {
                        var id = GetPropertyValue(collectionConfig.IdProperty, entity);
                        var name = GetPropertyValue(collectionConfig.NameProperty, entity);

                        result.Add(new PreValue()
                        {
                            Id = id?.ToString() ?? string.Empty,
                            Caption = name?.ToString() ?? string.Empty,
                            Value = id?.ToString() ?? string.Empty
                        });
                    }
                }
            }

            result = result.OrderBy(x => x.Id).ToList();
            return Task.FromResult(result);
        }

        public override List<Exception> ValidateSettings()
        {
            var exceptions = new List<Exception>();

            UIBuilderSectionConfiguration? configuration = ParseSourceConfiguration();
            if (configuration != null)
            {
                if (string.IsNullOrEmpty(configuration.Section))
                {
                    exceptions.Add(new Exception("'Section' setting has not been set"));
                }

                if (string.IsNullOrEmpty(configuration.Collection))
                {
                    exceptions.Add(new Exception("'Collection' setting has not been set"));
                }
            }

            return exceptions;
        }

        private UIBuilderSectionConfiguration? ParseSourceConfiguration()
        {
            if (string.IsNullOrEmpty(Source))
            {
                return null;
            }

            List<UIBuilderSectionConfigItem>? config = JsonSerializer.Deserialize<List<UIBuilderSectionConfigItem>>(Source);
            var result = new UIBuilderSectionConfiguration();

            if (config != null)
            {
                foreach (UIBuilderSectionConfigItem item in config)
                {
                    switch (item.Alias)
                    {
                        case "section":
                            result.Section = item.Value;
                            break;
                        case "collection":
                            result.Collection = item.Value;
                            break;
                        case "dataView":
                            result.DataView = item.Value;
                            break;
                        case "labels":
                            if (!string.IsNullOrEmpty(item.Value))
                            {
                                result.Labels = JsonSerializer.Deserialize<UIBuilderLabels>(item.Value);
                            }
                            break;
                    }
                }
            }

            return result;
        }

        private static object? GetPropertyValue(PropertyConfig? propertyConfig, object entity)
        {
            if (propertyConfig == null)
            {
                return null;
            }

            return propertyConfig.PropertyGetter?.Invoke(entity) ?? propertyConfig.PropertyExpression.Compile().DynamicInvoke(entity);
        }
    }

    internal class UIBuilderSectionConfigItem
    {
        [JsonPropertyName("alias")]
        public string? Alias { get; set; }

        [JsonPropertyName("value")]
        public string? Value { get; set; }
    }

    internal class UIBuilderSectionConfiguration
    {
        public string? Section { get; set; }
        public string? Collection { get; set; }
        public string? DataView { get; set; }
        public UIBuilderLabels? Labels { get; set; }
    }

    internal class UIBuilderLabels
    {
        [JsonPropertyName("plural")]
        public string? Plural { get; set; }

        [JsonPropertyName("singular")]
        public string? Singular { get; set; }
    }
}

And registered with:

public class MyComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
      builder.WithCollectionBuilder<FieldPreValueSourceCollectionBuilder>()
            .Add<UIBuilderRepository>();
    }
}

This will then make the UI Builder Repository available when creating a new prevalue source:

Once selected, you can pick a Section, Collection, and Data View from the configured UI Builder repositories:

For Umbraco Forms to work correctly, you need to include some client dependencies.

Client-Side Validation

Umbraco Forms ships with client-side form validation features provided by the ASP.NET Client Validation library.

You can use the following Razor helper to output script tags containing the dependencies. To access this method you will need a reference to Umbraco.Forms.Web:

@using Umbraco.Forms.Web
<head>
    @Html.RenderUmbracoFormDependencies(Url)
</head>

Url is a parameter passed into the method. It’s defined as a property on the base view model for an Umbraco template, so it will be automatically available in your Razor views.

Alternatively, you can add the dependencies to the body tag:

@using Umbraco.Forms.Web
...

<body>
    @Html.RenderUmbracoFormDependencies(Url)
</body>

All dependencies originate from your Umbraco Forms installation, which means that no external references are needed.

If you want to modify the rendering of the scripts, you can provide a object parameter named htmlAttributes. The contents of the object will be written out as HTML attributes on the script tags.

You can use this to apply async or defer attributes. For example:

If using async, please make sure to . This is necessary as it's not possible to guarantee that the asynchronous script will load in time to be recognized by the check. This can then cause a false positive warning.

It is possible to use jQuery as your validation framework instead of the ASP.NET Client Validation library.

To use jQuery validation, add the following client dependencies:

• jQuery (JavaScript library)

• jQuery validate (jQuery plugin that provides client-side Form validation)

• jQuery validate unobtrusive (Add-on to jQuery Validation that provides unobtrusive validation via data-* attributes)

Be sure to remove any calls to @Html.RenderUmbracoFormDependencies(Url).

The easiest way to add the dependencies is to fetch them from a . There are various CDN services you can use:

• For example: .

• Other CDN services you might want to look at are https://www.jsdelivr.com/ and https://cdnjs.com/about, which may offer better performance and more reliable service.

To add the three client dependencies, see the examples below:

Example within head tags.

Example within body tags.

When adding the script to the bottom of the page, you will also need to render the scripts. For more information, see article.

Forms output some JavaScript which is by default rendered right below the markup.

In many cases, you might prefer rendering your scripts at the bottom of the page. For example, before the closing </body> tag. This generally improves site performance.

In order to render your scripts where you want, you need to add a snippet to your template. Make sure you add it below your scripts, right before the closing </body> tag.

By default, Forms uses HttpContext.Items for tracking the forms rendered on a page. The stored values are used when rendering the form scripts and associated data.

The following snippet should be used.

@if (Context.Items.TryGetValue("UmbracoForms", out object? formIdsObject) && formIdsObject is IEnumerable<Guid> formIds)
{
    foreach (var formId in formIds)
    {
        @await Component.InvokeAsync("RenderFormScripts", new { formId, theme = "default" })
    }
}

If you have changed the configuration value of TrackRenderedFormsStorageMethod to use the legacy behavior TempData, the snippet is:

Read more about the TrackRenderedFormsStorageMethod configuration option in the article.

If you prefer to use a tag helper, that's an option too.

Firstly, in your _ViewImports.cshtml file, ensure you have a reference to the Umbraco Forms tag helpers with:

Then instead of reading from TempData and invoking the view component directly, you can use:

This will use the appropriate storage method that you have configured.

When setting up templates for Umbraco Forms, two separate script-rendering methods are involved, and both are required for forms to work correctly.

@Html.RenderUmbracoFormDependencies(Url), covered in the article, renders the ASP.NET Client Validation library, which Umbraco Forms uses by default for client-side validation. This helper goes in the <head> of your template. If your project uses jQuery validation instead, omit this call and reference dependencies manually, as described in the article.

The <umb-forms-render-scripts /> tag helper (or the equivalent view component calls shown above) renders form-specific scripts covering conditional field logic, field behaviors, and any theme JavaScript. This goes before the closing </body> tag.

Because both methods output <script> tags, they can appear to duplicate each other. The script contents are entirely different, however, and serve distinct purposes. A complete template uses both:

Omitting RenderUmbracoFormDependencies will break client-side validation. Omitting <umb-forms-render-scripts /> will break conditional fields and theme behaviour.

If you do not want to render the associated scripts with a Form, you need to explicitly say so. You need to make sure ExcludeScripts is checked/enabled, whether you are inserting your Form using a macro or adding it directly in your template.

To enable ExcludeScripts:

• Using the Insert Form with Theme macro:
• While inserting Forms directly in your template:

Umbraco Forms contains a built-in Get value from textfile Prevalue Source Type that stores the uploaded text file into the physical file system (by default in umbraco\Data\UmbracoForms\PreValueTextFiles).

You can replace the default implementation by writing your own IPreValueTextFileStorage and registering that using e.g. builder.Services.AddUnique<IPreValueTextFileStorage, CustomPreValueTextFileStorage>() (in Program.cs or a composer).

You can also use/inherit from PreValueTextFileSystemStorage to change the underlying IFileSystem that's used to store the prevalue text files.

You can use the following composer to move the prevalue text files into the media file system. If the media file system is using Azure Blob Storage, this will remove the files from the local physical file system.

You need to manually move the existing files from umbraco\Data\UmbracoForms\PreValueTextFiles to your media storage. The final file path/URL will look like ~/media/PreValueTextFiles/{GUID}/{filename.txt} and be accessible from the browser.

First, install and configure the Forms storage container, for example by adding the following to your appsettings.json:

Next, add the following composer that adds the Forms storage container and stores the prevalue text files into Azure Blob Storage (in forms/PreValueTextFiles/{GUID}/{filename.txt}):

You need to manually move the existing files from umbraco\Data\UmbracoForms\PreValueTextFiles to your storage container. If you've disabled public access, the stored files are not accessible from the browser.

In this section, you can find a set of different tutorials to use when creating and working with Umbraco Forms.

Tutorials

Learn how to configure a Document Type, build a Contact Form, and add it to a content page on your website.

Learn how to build a multi-page form and use conditional logic to control which questions appear based on earlier answers.

Walk through creating a Zapier webhook trigger and using a form workflow to send entries to other apps.

In Umbraco Forms, reCAPTCHA V2 comes out of the box to help you to protect your site from spam, malicious people, and so on.

Follow these steps to enable reCAPTCHA V2 in Umbraco Forms:

1. Go to the Forms section in the backoffice.

2. Find the form that should have ReCAPTCHA v2 enabled.

3. Add a new question and select

Revert application of keys and indexes

This builds on the "adding a type to the provider model" chapter

Add a new class to your project and have it inherit from Umbraco.Forms.Core.WorkflowType, and implement the class. For this sample, we will focus on the execute method. This method processes the current record (the data submitted by the form) and have the ability to change data and state.

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
using Umbraco.Forms.Core;
using Umbraco.Forms.Core.Enums;
using Umbraco.Forms.Core.Persistence.Dtos;

namespace MyFormsExtensions
{
    public class TestWorkflow : WorkflowType
    {
        private readonly ILogger<TestWorkflow> _logger;

        public TestWorkflow(ILogger<TestWorkflow> logger)
        {
            _logger = logger;

            this.Id = new Guid("ccbeb0d5-adaa-4729-8b4c-4bb439dc0202");
            this.Name = "TestWorkflow";
            this.Description = "This workflow is just for testing";
            this.Icon = "icon-chat-active";
            this.Group = "Services";
        }

        public override Task<WorkflowExecutionStatus> ExecuteAsync(WorkflowExecutionContext context)
        {
            // first we log it
            _logger.LogDebug("the IP " + context.Record.IP + " has submitted a record");

            // we can then iterate through the fields
            foreach (RecordField rf in context.Record.RecordFields.Values)
            {
                // and we can then do something with the collection of values on each field
                List<object> vals = rf.Values;

                // or get it as a string
                rf.ValuesAsString(false);
            }

            //Change the state
            context.Record.State = FormState.Approved;

            _logger.LogDebug("The record with unique id {RecordId} that was submitted via the Form {FormName} with id {FormId} has been changed to {RecordState} state",
               context.Record.UniqueId, context.Form.Name, context.Form.Id, "approved");

            return Task.FromResult(WorkflowExecutionStatus.Completed);
        }

        public override List<Exception> ValidateSettings()
        {
            return new List<Exception>();
        }
    }
}

Information available to the workflow

Record information

The ExecuteAsync() method gets a WorkflowExecutionContext which has properties for the related Form, Record, and FormState. This parameter contains all information related to the workflow.

The Record contains all data and metadata submitted by the form. As shown in the example above, you can iterate over all RecordField values in the form. You can also retrieve a specific record field by alias using the following method:

Having obtained a reference to a record field, the submitted value can be retrieved via:

The ValuesAsString will JSON escape the result by default. If you do not want this escaping to occur, pass false as the parameter.

If the field stores multiple values, they are delimited with a comma. In many cases, you can safely split on that delimiter to obtain the individual values. However, this can lead to issues if the prevalues being selected also contain commas. If that's a concern, the following extension method is available in Umbraco.Forms.Core.Extensions to correctly parse the selected prevalues:

The Form references the form the record is from and FormState provides its state (submitted or approved).

Other context, such as the current HttpContext, if needed can be passed as constructor parameters (for example: the HttpContext can be accessed by injecting IHttpContextAccessor).

A record field that stores a date is formatted for whoever reads it. ValuesAsString has an overload that takes a RecordFieldDateFormat and, optionally, a culture:

The options are:

Magic strings in your workflow's own settings are formatted the same way. Override PlaceholderDateFormat to choose the format:

Use Culture when a person reads the setting, such as an email body. Use Iso when another system reads it, such as a webhook URL. The default is Invariant, which keeps the behavior of earlier versions.

The GetConfigurationErrors method can be overridden to report when required configuration is missing. By default it returns an empty collection. The workflow type is then considered configured and available for use.

The workflow type shows as unavailable in the backoffice when the method returns error messages. It remains locked until the reported issues are resolved. This is useful when your workflow depends on external API keys or other application configuration settings.

The IsConfigured property is derived from this method. It returns true when no configuration errors are reported.

To use the new workflow type, you will need to register it as part of application startup.

In this article, you will find information about accessing the Forms Advanced Options and the features available to customize your Form.

To access the Form Advanced Options:

1. Navigate to the Forms section.

2. Open a Form you wish to customize.

3. Click Advanced in the top-right corner of the screen.

Sometimes you might have a field in your Form, that you want to show only if the user has entered a specific value in another field.

You can achieve this setting by using conditional logic on Fields.

Take a look at the following:

In this case, it makes sense to only show the email or phone field when the corresponding option is selected in the How should we contact you? field.

To enable conditions for the Email and Phone fields, do the following:

1. Click the cog

Umbraco Forms stores a version of a form each time the form is saved. The workflows attached to the form are stored with it. You can return the form to any stored version.

1. Go to the Forms section.

2. Select the form you want to roll back.

3. Open the Actions menu and select Rollback.

There are multiple built-in Workflow Types that can be used to extend the functionality of your form. Do you want to post the submitted form as XML, send the data as an email, or send a notification through another messaging system? These are a few of the options you can choose when working with Umbraco Forms.

Video Tutorial

Change Record State

Used to automatically Approve Record, Reject Record or Delete Record once it is submitted. Configure words that you want to match and select whether these words should trigger an approval or deletion of the record.

Post as XML

Used to post the Form as an XML to a specified URL. The following configuration can be set:

• Workflow Name

• URL (required)

• Method - POST, GET, PUT or DELETE

• XSLT File - used to transform the XML

• Fields - map form fields to values that are sent as HTTP headers with the request

• Default Element For Fields - choose whether the field caption or alias is used as the XML element name

• User

• Password

Date values in the XML are written in the ISO 8601 format. The receiving system reads them without having to guess the format.

Saves the result of the Form as an XML file by using XSLT. The following configuration can be set:

• Workflow Name

• Path (required) - where to save the XML file

• File extension (required)

• XsltFile - used to transform the XML

The path needs to point to a folder, not a file name. The files are then stored locally, and relative paths are resolved to the content root.

Date values in the saved file are written in the ISO 8601 format.

Saves a submitted Form as a new content node. You need to choose a Document type and match the fields in the Form with the properties on the selected Document Type.

You can also choose to set a static value to fill in the properties:

In the example above, a Document Type called Blogpost is selected for creating the new Content node.

The value from the Name field will be added as the Node Name property in the new Content node. The value from the Email field will be used as the Content property.

The following configuration can be set:

• Workflow Name

• Publish - choose whether to publish the node on submission

• Where to save - choose a section in the content tree where this new node should be added

A form field that stores a date is mapped to a date property as a date value. A day-first date such as 05/07/2027 from an en-GB entry is saved as 5 July.

Sends the result of the Form to the specified email address. The following configuration can be set:

• Workflow Name

• Message (required)

• Attachment - specify whether file uploads should be attached to the email

• Recipient Email (required)

For fields that accept multiple email addresses (Recipient Email, CC Email, BCC Email), you can separate addresses using semicolons (';') or commas (','). For example:

If the Sender Email field is not populated, the address used will be read from CMS configuration.

The value configured at Umbraco:CMS:Global:Smtp:From will be used if provided.

If that is not set, the value configured at Umbraco:CMS:Content:Notifications:Email will be used.

The fallback behavior also applies to the other email workflows.

A date value in the email uses the culture the entry was submitted with.

Uses a template to send the results of the Form to a specified email address.

You can create your own custom Razor templates to be used to send out emails upon Forms submission. Read more about how to create these templates in the article.

The following configuration can be set:

• Workflow Name

• Email Template (required) - specify which template you want to use

• Header text - formatted text that will be rendered above the form entry details

• Footer text - formatted text that will be rendered below the form entry details