--- title: Customizing the Form widget related: - https://docs.kentico.com/13/managing-website-content/forms/placing-forms-on-pages.md - https://docs.kentico.com/13/developing-websites/page-builder-development/developing-widgets/extending-widgets.md --- > Agent instructions: > **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown. > > - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version. > - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt). This page describes how you can customize the markup of forms rendered using the [Form page builder widget](https://docs.kentico.com/13/managing-website-content/forms/placing-forms-on-pages.md). The page is divided into the following sections: - [Customizing the HTML markup of rendered forms](#customizing-the-html-markup-of-rendered-forms) – describes how to set static, site-wide rendering configurations used when forms or form fields are rendered. - [Contextually modifying form markup](#contextually-modifying-form-markup) – introduces events that you can handle to dynamically modify markup when forms or individual form fields are rendered (based on the current context, such as the field type, properties, or form name). - [Examples](#examples) – provides a set of sample form customization use cases. > **Tip:** **Tip**: If you only need to add custom content wrapped around the default form markup, you can use widget nesting and create an extended form widget. To learn more, see [Extending widgets](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-widgets/extending-widgets.md). ## Customizing the HTML markup of rendered forms ### Form markup Forms rendered using the Form widget are by default wrapped by an empty _'div'_ block element. You can customize the markup of forms rendered using the widget by setting the static **FormWidgetRenderingConfiguration.Default** property. The **FormWidgetRenderingConfiguration** type exposes a group of properties you can configure to customize the markup surrounding the form, as well as the HTML attributes of the form's _Submit_ button and _form_ HTML element. | Property | Type | Description | | -------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FormWrapperConfiguration | [FormWrapperRenderingConfiguration](#customizingtheformwidget-formwrapperrenderingconfiguration) | Specifies the HTML element (and its attributes) wrapping the entire form. If _null,_ no wrapping element is rendered for forms. | | FormHtmlAttributes | IDictionary | Specifies HTML attributes applied to the _form_ HTML element.**Note:** **Setting the id attribute of forms**
You can use this property to set the _id_ attribute of the form element, which is by default randomly generated. However, note that this sets the identical _id_ for **ALL** form widget instances. As a result, you can place no more than one form via the _Form_ widget per page. | | SubmitButtonHtmlAttributes | IDictionary | Specifies HTML attributes applied to the submit button. | ** FormWrapperConfiguration** is of the **FormWrapperRenderingConfiguration** type, which holds information about HTML elements wrapping each form. It exposes the following properties: | Property | Type | Description | | ------------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ElementName | string | The name of the HTML element wrapping the form. | | HtmlAttributes | IDictionary | A dictionary of _ElementName_'s attributes. | | ChildConfiguration | ElementRenderingConfiguration | May hold additional _[ElementRenderingConfigurations](#customizingtheformwidget-elementrenderingconfiguration)_. Use this property when you wish to nest multiple wrapping elements. | | CustomHtmlEnvelopeString | string | Adds custom HTML content before or after the form wrapper. The HTML string needs to contain the **FormWrapperRenderingConfiguration.CONTENT\_PLACEHOLDER** constant to mark where you wish to render the form wrapper and the body of the form. See [CONTENT\_PLACEHOLDER usage](#content_placeholder-usage) for an example.
**Note**: Content of the _CustomHtmlEnvelopeString_ is only rendered once per page load. The form wrapper elements and form body may be rendered repeatedly, for example when form validation fails or when processing field visibility conditions. | For illustration, the following pseudocode shows the configurable HTML structure of each form: ```csharp
...
``` ### Form field markup By default, each form field section contains placeholder '_div_' block elements. You can customize the wrapping HTML markup and the attributes of each form field by modifying the **FormFieldRenderingConfiguration.Widget**property. _FormFieldRenderingConfiguration_ exposes a collection of properties you can configure to alter the HTML markup of the rendered form, its form fields, and each field's subsections, such as label or explanation text: | Property | Type | Description | | ----------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | RootConfiguration | [ElementRenderingConfiguration](#customizingtheformwidget-elementrenderingconfiguration) | Specifies the HTML element (and its attributes) wrapping the label and corresponding input element. If _null,_ no wrapping element is rendered for the given form field. | | LabelWrapperConfiguration | ElementRenderingConfiguration | Specifies the HTML element (and its attributes) wrapping the labelelement. | | LabelHtmlAttributes | IDictionary | Specifies HTML attributes applied to the labelelement. | | ColonAfterLabel | bool | Indicates whether a colon ':' character is rendered after the text of the label element. Set to _true_ by default. | | EditorWrapperConfiguration | ElementRenderingConfiguration | Specifies the HTML element (and its attributes) wrapping the field's input, validation message, and explanation text. If _null,_ no wrapping HTML element is rendered. | | EditorHtmlAttributes | IDictionary | Specifies HTML attributes applied to the field's inputelement. | | ComponentWrapperConfiguration | ElementRenderingConfiguration | Specifies the HTML element (and its attributes) wrapping the field's input element. | | ExplanationTextWrapperConfiguration | ElementRenderingConfiguration | Specifies the HTML element (and its attributes) wrapping the explanation text – a short message usually rendered under the input fields – of the component. If _null,_ no wrapping HTML element is rendered. | | SuppressValidationMessages | bool | Indicates whether validation messages are rendered individually for each form field. | Some properties of _FormWidgetRenderingConfiguration_ and _FormFieldRenderingConfiguration_ are of the **ElementRenderingConfiguration** type, which is used to specify the wrapping HTML element. _ElementRenderingConfiguration_ exposes the following properties: | Property | Type | Description | | ------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ElementName | string | The name of the HTML element wrapping the given form field component. | | HtmlAttributes | IDictionary | Contains _ElementName_'s attributes. | | ChildConfiguration | ElementRenderingConfiguration | May hold additional _ElementRenderingConfigurations_. Use this property to nest multiple wrapping elements for a given form field section. | | CustomHtml | IHtmlString | Sets custom HTML markup instead of the corresponding _ElementRenderingConfiguration_. The HTML string needs to contain **ElementRenderingConfiguration.CONTENT\_PLACEHOLDER** to mark where you wish to render the remaining sub-elements within the given wrapping element. See [CONTENT\_PLACEHOLDER usage](#content_placeholder-usage) for an example.
**Note**: If the _CustomHtml_ property is set, the system **disregards**the element and HTML attributes specified in _ElementName_ and _HtmlAttribute_and renders the value of this property as **raw HTML** instead. Moreover, further nesting of additional configurations via _ChildConfiguration_ becomes disabled. | For illustration, the following pseudocode shows the configurable structure of individual form fields: ```csharp ``` ## Contextually modifying form markup In addition to setting the global rendering configuration, you can modify forms and form fields as they are being rendered. This allows you to adjust the resulting markup (accessibility or data attributes, CSS classes, etc.) based on contextual information. For example, you can adjust form markup based on the properties of specific fields or the name of the form. The system provides the following two events that fire when forms or form fields are rendered: - [FormWidgetRenderingConfiguration.GetConfiguration](#formwidgetrenderingconfiguration.getconfiguration) – fired when a form inserted using the _Form_ page builder widget is rendered. - [FormFieldRenderingConfiguration.GetConfiguration](#formfieldrenderingconfiguration.getconfiguration) – fired when individual form fields are rendered. ### FormWidgetRenderingConfiguration.GetConfiguration **Namespace**: Kentico.Forms.Web.Mvc.Widgets Fired when a form inserted via the _Form_ widget is rendered. The **GetFormWidgetRenderingConfigurationEventArgs** event arguments allow you to access or modify: | Property | Type (and select properties) | Description | | -------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Configuration | FormWidgetRenderingConfiguration | The rendering configuration of the form. See [Form markup](#form-markup) for a detailed description of the _FormWidgetRenderingConfiguration_ type. | | Form | BizFormInfo
Form
FormName
FormDisplayName | The system object representing the form. | | FormComponents | IEnumerable | Contains a collection of form fields being rendered on this request. This collection can change when rendering forms containing [smart fields](https://docs.kentico.com/13/managing-website-content/forms/using-smart-fields-in-forms.md) and upon [visibility condition](https://docs.kentico.com/13/developing-websites/form-builder-development/defining-field-visibility-conditions.md) re-evaluation. | | FormWidgetProperties | FormWidgetProperties | Contains the properties of the current [Form widget](https://docs.kentico.com/13/managing-website-content/forms/placing-forms-on-pages.md) instance. | See [Adding contextual markup to forms](#adding-contextual-markup-to-forms) for an example. ### FormFieldRenderingConfiguration.GetConfiguration **Namespace**: Kentico.Forms.Web.Mvc Fired whenever a form field is being rendered (on the live site or when viewing pages in the Pages application). The **GetFormFieldRenderingConfigurationEventArgs** event arguments allow you to access or modify: | Property | Type (and select properties) | Description | | ------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Configuration | FormFieldRenderingConfiguration | The rendering configuration of the form field. See [Form field markup](#form-field-markup) for a detailed description of the _FormFieldRenderingConfiguration_ type. | | FormComponent | FormComponent
BaseProperties
Definition | Allows you to access type and configuration information of the rendered form component.
**BaseProperties** holds the component's properties, such as the field's required status, label, and explanation text, as configured via the Form builder's [properties panel](https://docs.kentico.com/13/managing-website-content/forms/composing-forms.md#configuring-field-properties) or programmatically using [editing attributes](https://docs.kentico.com/13/developing-websites/form-builder-development/developing-form-components/defining-form-component-properties.md).
**Definition** holds information under which the corresponding form component was [registered into the system](https://docs.kentico.com/13/developing-websites/form-builder-development/developing-form-components.md#registering-form-components), such as its _identifier_, _name_, or _description_. | To access contextual information about the form field, use **GetBizFormComponentContext**: ```csharp BizFormComponentContext context = e.FormComponent.GetBizFormComponentContext(); ``` You can access the code and display names, as well as other system data of the form containing the currently processed form field via **BizFormComponentContext.FormInfo**. See [Adding contextual markup to form fields](#adding-contextual-markup-to-form-fields) for an example. ## Examples This section contains a set of examples demonstrating usage of the form customization API: - [Setting global rendering configurations](#setting-global-rendering-configurations) – shows how to set a static, site-wide configuration using _FormFieldRenderingConfiguration_ and _FormWidgetRenderingConfiguration_. - [CONTENT\_PLACEHOLDER usage](#content_placeholder-usage) – demonstrates the impact of setting _CustomHtml_ on the resulting HTML structure. - [Adding contextual markup to forms](#adding-contextual-markup-to-forms) – uses the [FormWidgetRenderingConfiguration.GetConfiguration](#formwidgetrenderingconfiguration.getconfiguration) event to contextually modify form markup. - [Adding contextual markup to form fields](#adding-contextual-markup-to-form-fields) – uses the [FormFieldRenderingConfiguration.GetConfiguration](#formfieldrenderingconfiguration.getconfiguration) event to contextually modify form field markup. ### Setting global rendering configurations We recommend setting the rendering configurations during the live site project's startup. For example, within the initialization code of a [custom module](https://docs.kentico.com/13/custom-development/creating-custom-modules/initializing-modules-to-run-custom-code.md): ```csharp using Kentico.Forms.Web.Mvc; using Kentico.Forms.Web.Mvc.Widgets; namespace FormBuilderCustomizations { public class FormBuilderStaticMarkupConfiguration { public static void SetGlobalRenderingConfigurations() { // Modifies the default FormFieldRenderingConfiguration for the 'Form' widget // Specifying a new FormFieldRenderingConfiguration instance completely replaces the default Kentico configuration FormFieldRenderingConfiguration.Widget.RootConfiguration = new ElementRenderingConfiguration { ElementName = "div", HtmlAttributes = { { "class", "form-field" } } }; FormFieldRenderingConfiguration.Widget.ExplanationTextWrapperConfiguration = new ElementRenderingConfiguration { ElementName = "div", HtmlAttributes = { { "class", "explanation-text" } } }; // Sets a new rendering configuration for the 'Form' widget, adding attributes // to the form element and the submit button and wrapping the form in two 'div' blocks FormWidgetRenderingConfiguration.Default = new FormWidgetRenderingConfiguration { // Form element HTML attributes FormHtmlAttributes = { { "formattribute", "attributevalue" } }, // Submit button HTML attributes SubmitButtonHtmlAttributes = { { "class", "submit-button" } }, // Elements wrapping the Form element FormWrapperConfiguration = new FormWrapperRenderingConfiguration { ElementName = "div", HtmlAttributes = { { "class", "form-widget-form" } }, // Adds an additional div element wrapper ChildConfiguration = new ElementRenderingConfiguration { ElementName = "div" } } }; } } } ``` Call the _SetGlobalRenderingConfigurations_ method on application start. For example, as part of [custom module initialization code](https://docs.kentico.com/13/custom-development/creating-custom-modules/initializing-modules-to-run-custom-code.md). Forms displayed via the _Form_ widget are now rendered using the modified rendering configurations. ### CONTENT\_PLACEHOLDER usage The **CONTENT\_PLACEHOLDER** property, part of _FormFieldRenderingConfiguration_ and _FormWrapperRenderingConfiguration_, acts as a marker that tells the system where to render the inner HTML markup in case _CustomHtml_ (or _CustomHtmlEnvelopeString)_ is set as part of the configuration. For example, modifying _FormFieldRenderingConfiguration_ in the following manner: ```csharp FormFieldRenderingConfiguration.Widget.EditorWrapperConfiguration.CustomHtml = MvcHtmlString.Create($"
{ElementRenderingConfiguration.CONTENT_PLACEHOLDER}
"); ``` Results in this HTML structure for form fields: ```csharp // Any existing 'EditorWrapperConfiguration' is discarded and its markup gets replaced // CONTENT_PLACEHOLDER indicates where the inner markup is placed - wrapped by a 'div' element in this case.
``` ### Adding contextual markup to forms The following example uses the [FormWidgetRenderingConfiguration.GetConfiguration](#formwidgetrenderingconfiguration.getconfiguration) event to: - Render the **display name** of the form above the form element using _CustomHtmlEnvelopeString_. - Contextually assign additional attributes only to the **ContactUs** form's _Submit_ button. Register a new _FormWidgetInjectMarkup_ handler for the _FormWidgetRenderingConfiguration.GetConfiguration.Execute_ event: ```csharp using System; using System.Web.Mvc; using Kentico.Forms.Web.Mvc.Widgets; namespace FormBuilderCustomizations { public class FormWidgetMarkupInjection { public static void RegisterEventHandlers() { FormWidgetRenderingConfiguration.GetConfiguration.Execute += FormWidgetInjectMarkup; } private static void FormWidgetInjectMarkup(object sender, GetFormWidgetRenderingConfigurationEventArgs e) { e.Configuration.FormWrapperConfiguration = new FormWrapperRenderingConfiguration { // Renders the form's display name above the form using the 'CustomHtmlEnvelope' property // FormWrapperRenderingConfiguration.CONTENT_PLACEHOLDER acts as a placeholder for the form's body in the resulting markup CustomHtmlEnvelope = MvcHtmlString.Create($@"

{e.Form.FormDisplayName}

{FormWrapperRenderingConfiguration.CONTENT_PLACEHOLDER}") }; // Sets additional attributes only for specific forms. Since the 'class' attribute is fairly // common, checks if the key is already present and inserts or appends the key accordingly. if (e.Form.FormName.Equals("ContactUs", StringComparison.InvariantCultureIgnoreCase)) { if (e.Configuration.SubmitButtonHtmlAttributes.ContainsKey("class")) { e.Configuration.SubmitButtonHtmlAttributes["class"] += " contactus-submit-button"; } else { e.Configuration.SubmitButtonHtmlAttributes["class"] = "contactus-submit-button"; } } } } } ``` Call the _RegisterEventHandlers_ method on application start. For example, as part of [custom module initialization code](https://docs.kentico.com/13/custom-development/creating-custom-modules/initializing-modules-to-run-custom-code.md). ### Adding contextual markup to form fields The following example uses the [FormFieldRenderingConfiguration.GetConfiguration](#formfieldrenderingconfiguration.getconfiguration) event to: - Add the semantic _aria-required_ WAI-ARIA and _required_ HTML5 attributes to form fields marked as **Required** via the form builder properties panel, and append a red asterisk after the field's label using CSS. - Assigns additional attributes to **TextArea** fields, provided the form contains any. - Adds additional attributes to fields that are part of the **ContactUs** form. Register a new _KenticoComponentMarkupInjection_ handler for the _FormFieldRenderingConfiguration.GetConfiguration.Execute_event: ```csharp using System; using Kentico.Forms.Web.Mvc; namespace FormBuilderCustomizations { public class FormFieldMarkupInjection { public static void RegisterEventHandlers() { // Contextually customizes the markup of rendered form fields FormFieldRenderingConfiguration.GetConfiguration.Execute += InjectMarkupIntoKenticoComponents; } private static void InjectMarkupIntoKenticoComponents(object sender, GetFormFieldRenderingConfigurationEventArgs e) { // Only injects additional markup into default Kentico form components if (!e.FormComponent.Definition.Identifier.StartsWith("Kentico", StringComparison.InvariantCultureIgnoreCase)) { return; } // Adds WAI-ARIA and HTML5 accessibility attributes to form fields marked as 'Required' via the Form builder interface AddAccessibilityAttributes(e); // Assigns additional attributes to 'TextArea' fields AddFieldSpecificMarkup(e); // Assigns additional attributes to fields rendered as part of a specified form AddFormSpecificMarkup(e); } private static void AddAccessibilityAttributes(GetFormFieldRenderingConfigurationEventArgs e) { if (e.FormComponent.BaseProperties.Required) { // Adds the 'aria-required' and 'required' attributes to the component's 'input' element e.Configuration.EditorHtmlAttributes["aria-required"] = "true"; e.Configuration.EditorHtmlAttributes["required"] = ""; // Appends an asterisk to the component's 'Label' element. Since the class attribute is fairly // common, checks if the key is already present and inserts or appends the key accordingly. if (e.Configuration.LabelHtmlAttributes.ContainsKey("class")) { e.Configuration.LabelHtmlAttributes["class"] += " required-field-red-star"; } else { e.Configuration.LabelHtmlAttributes["class"] = "required-field-red-star"; } } } private static void AddFieldSpecificMarkup(GetFormFieldRenderingConfigurationEventArgs e) { // Sets a custom CSS class for the wrapping element of 'TextAreaComponent' type form fields if (e.FormComponent is TextAreaComponent) { if (e.Configuration.RootConfiguration.HtmlAttributes.ContainsKey("class")) { e.Configuration.RootConfiguration.HtmlAttributes["class"] += " text-area-styles"; } else { e.Configuration.RootConfiguration.HtmlAttributes["class"] = "text-area-styles"; } } } private static void AddFormSpecificMarkup(GetFormFieldRenderingConfigurationEventArgs e) { // Gets the context of the Form for which the field is being rendered BizFormComponentContext context = e.FormComponent.GetBizFormComponentContext(); // Modifies only form fields rendered as part of the 'ContactUs' form if (context.FormInfo.FormName.Equals("ContactUs", StringComparison.InvariantCultureIgnoreCase)) { e.Configuration.ColonAfterLabel = false; e.Configuration.EditorHtmlAttributes["data-formname"] = context.FormInfo.FormDisplayName; } } } } ``` Add the _required-field-red-star_ class that renders a red asterisk after a required field's label to your site's CSS: ```css .required-field-red-star::after { content: "*"; color: red; } ``` Call the _RegisterEventHandlers_ method on application start. For example, as part of [custom module initialization code](https://docs.kentico.com/13/custom-development/creating-custom-modules/initializing-modules-to-run-custom-code.md).