Walkthrough: Creating a custom form element


Build a new form element.

Sitecore Forms comes with default form elements that you can drag and drop on your form. To build a custom form element, you must create a new field template, a new class that derives from the FieldViewModel class, a razor view file, and a field type item that uses the razor view file to do the rendering.

You can add a custom form element category for your form element.

You can also add add custom validation to elements.


This walkthrough uses an example of a video element. The scenario is just an example describing the steps involved to build a custom form element.

A Sitecore template defines form elements. To create a new element, you must create its template first.

To add a template:

  1. In the Sitecore Content Editor, navigate to sitecore/Templates and create a new folder. For example, the Fields folder.

  2. Click the new folder and then click New Template.

  3. Enter a name, select the Base template: Templates/System/Forms/Fields/Field, and click Next.

  4. Click the new template, and on the Builder tab, add the relevant template fields. For example, to add an element that adds a YouTube video to a form, you must specify the link to the YouTube video and set the width and the height of the video:

    • URL (single line text)

    • Width (integer)

    • Height (integer)


    Make sure to select the Shared check box.

  5. Save the template.

  6. On the ribbon, click Options, and click Standard values.


Make sure to create standard values for the field templates. The standard values items are used to populate the default field values when the field is added from the form elements pane to the canvas. If a field template does not have standard values, the element cannot be dropped on the form.

Now you can create the logic for the View model by creating a new class that derives from the FieldViewModel class. You can control how the form element displays by arranging the HTML and inserting your own CSS classes.

To add the new class:

  1. In Visual Studio, create a new class library project. For example, FormsDemo.

  2. Add the FieldViewModel class. For example, add the VideoViewModel class:

    public class VideoViewModel : FieldViewModel


    The models of the posted fields are stored in session state. They must be marked [Serializable] in order to be stored.

  3. Add the properties. For example, add the Url, Width, and Height.

    namespace FormsDemo
      public class VideoViewModel : FieldViewModel
    	public string Url { get; set; }
    	public int Width { get; set; }
    	public int Height {get; set;}
    	protected override void InitItemProperties(Item item)
        // on load of the form
            Url = StringUtil.GetString(item.Fields["Url"]);
    	Width = MainUtil.GetInt(item.Fields["Width"]?.Value, 0);
    	Height = MainUtil.GetInt(item.Fields["Height"]?.Value, 0);
  4. Override the InitItemProperties and the UpdateItemFields methods.

    protected override void InitItemProperties(Item item)
    	// on load of the form
    	Url = StringUtil.GetString(item.Fields["Url"]);
    	Width = MainUtil.GetInt(item.Fields["Width"]?.Value, 0);
    	Height = MainUtil.GetInt(item.Fields["Height"]?.Value, 0);
    protected override void UpdateItemFields(Item item)
    	// upon save
    	item.Fields["Url"]?.SetValue(Url, true);
    	item.Fields["Width"]?.SetValue(Width.ToString(CultureInfo.InvariantCulture), true);
    	item.Fields["Height"]?.SetValue(Height.ToString(CultureInfo.InvariantCulture), true);
  5. Build the project and deploy the FormsDemo.dll to the Sitecore website bin folder.

The next step is to create the razor view file:

  1. For example, for the video element, create the Video.cshtml razor view file:

    Video.cshtml razor view file.
  2. Add the razor view file to the new class library project that you created earlier. The default razor view files for Sitecore Forms are stored in: Website/Views/FormBuilder/FieldTemplates. For example, add the Video.cshtml file to the FormsDemo folder and save.


Now you can add the sections that appear in the Form elements pane. For example, the Single-line text element contains the following sections: Details, Validation, Styling, and Advanced settings.

Single-line text form element.

In this example, for the video element, we want the user to be able to set the Field name, URL, Width, and Height properties. The next steps describe how to create the property editor that is displayed in the Form elements pane.

To add sections to the Form elements pane:

  1. In Sitecore Rocks, expand the core database and right-click the Settings folder that contains the layout parameters for all field property editors: /sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Settings

  2. Click Add, and click New item.

  3. In the Add New Item dialog box, search for and select the Form Parameters template, enter a name, for example, Video, and click OK.

    Add new item using Form parameters template
  4. Right-click the Video item that you just created and click Add, click New item.

  5. To add the new sections for your custom element, search for and select the FormSection template.


    The FormSection template is the section visualization template for the Speak form and enables you to reuse rendering parameters for the section and field editors.

  6. Enter a name for the new item and click OK. For example, enter Details to add the Details section.

    Add new item for Details section
  7. Right-click the Details item that you just created and click Add, then click New item.

    For example, to set the FieldName, Width, Height, and URL properties of the video item, you can reuse the FieldName item that is used in the out-of-the-box form elements.

  8. Search and select FormTextBox Parameters, enter a name (for example, Width) and click OK.

    FormTextBox parameters


    You must select Speak 2.0 parameters.

  9. Repeat these steps to create all the relevant items, for example, the Height and URL items:


Now you must configure the parameters for each newly created field editor. For example, you can set the text and position of the label.

  1. Open the Width item and navigate to the Form section. Edit the following fields:

    • FormLabel – specify the textbox label that displays in the Form elements pane.

    • IsLabelOnTop – select to position the label on top of the input. For consistency, it is recommended that you select this checkbox for all field editor properties.

    • BindingConfiguration – lists the FormData property names and corresponding component bindable properties. The left pane specifies the field model property (note that the property name is in camelCase) and the right pane specifies which editor property to read to update the field model property.

  2. In the Details section, reference the field editors in the following fields:

    • ConfigurationItem – specify the parameters for the Speak Expander. You can reuse the DetailsExpander item in: sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common/Sections

    • ControlDefinitions – specify the field editors that display in the Form elements pane, in order of reference. You can reuse the Fieldname item in: /sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common/Details

  3. In ControlDefinitions, select Fieldname, and select Width, Height, and URL items you created earlier.


    For convenience, you can copy and adjust already configured sections from other editors.

  4. Create the section item using the FormSection template, for example, name it Styling.

  5. To edit the Styling item, in the Data section, edit the following fields:

    • ConfigurationItem – add the reference to the Styling Expander: /sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common/Sections/StylingExpander

    • ControlDefinitions – add the reference to the CSS Class: /sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common/Styling/CssClass


Now you can create the custom field in Sitecore and tie it all together.

To create the field type item:

  1. Go to /sitecore/system/Settings/Forms/Field Types/Basic folder and add a new item.

  2. Base the item on the /System/Forms/Field Type template, enter a name and click Insert. For example, Video.

  3. Edit the Settings section fields:

    • View Path – specify the path that points to the razor view file. For example, FormsDemo/Video.

    • Model Type – specify the model type that references the class name. For example, FormsDemo.VideoViewModel,FormsDemo.

    • Property Editor – point to the item you created earlier. For example, select the property editor for the Video item.

      Set allowed validations
  4. In the Appearance section, edit the following fields:

    • Icon – select the icon that will appear in the Forms elements pane. For example, OfficeWhite/32x32/videotape.png.


      To set the icon that appears in the Content Editor, make sure the Standard fields  checkbox is selected and set the standard values icon field value as the corresponding icon from the non-white Office theme Office/32x32/videotape.png

    • BackgroundColor – select the background color for the icon that will appear in the Form elements pane. For example, Sky.

  5. In the Field template field, specify the field template you created previously. For example, sitecore/Templates/FormsDemo/Fields/Video. When you now create a new form, the custom video element is available in the Forms element pane:

    Video element in Form elements pane