---
title: Developing custom form layouts
related:
  - https://docs.kentico.com/k12sp/developing-websites/form-builder-development.md
  - https://docs.kentico.com/k12sp/managing-website-content/forms/composing-forms.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).

The layout of forms composed via the Kentico [form builder](https://docs.kentico.com/k12sp/developing-websites/form-builder-development.md) is based on elements called **sections**. Each form section defines a block of HTML code containing one or more zones. These zones can then hold any number of form fields (based on [form components](https://docs.kentico.com/k12sp/developing-websites/form-builder-development/developing-form-components.md)).

When [creating forms in the form builder interface](https://docs.kentico.com/k12sp/managing-website-content/forms/composing-forms.md) of the _Forms_ application, editors first add or adjust the sections, and then add individual fields into the resulting zones.

The system provides a **Default** form section which organizes fields in a basic single-column layout (one zone). The default section is automatically added into new forms, and in cases where an editor removes the last section from a form. If you wish to use more advanced layouts for fields in your forms, you need to develop and register your own form sections.

> **Tip:** **Form submit button**
>
> The submit button of a form is rendered after the last section (when [displaying forms](https://docs.kentico.com/k12sp/managing-website-content/forms/displaying-forms.md) on the website using the _Form_ widget). If you need to adjust the position of the submit button, use appropriate CSS styling in your site's stylesheet.

## Developing form sections

Form sections are implemented as controllers that return HTML markup containing form zones.

Form sections are designed to be used in the global scope and therefore must be registered in the application root of your MVC project (not in an MVC Area). Registering form sections in MVC Areas may lead to unexpected behavior.

### Implementing form section controllers

When creating controllers for form sections, implement the default **Index** action which retrieves the section markup. The action must return the section's HTML content, typically a partial view.

The recommended location to store form section controllers is the _\~/Controllers/FormSections_ folder.

> **Note:** **Do not disable POST requests for the _Index_ action**
>
> POST requests cannot be disabled for the _Index_ action (e.g., by using the _HttpGet_ attribute). POST requests to the _Index_ action are used by the form builder feature.

```csharp

    public class TwoColumnFormSectionController : Controller
    {
        // Action used to retrieve the section markup
        public ActionResult Index()
        {
            return PartialView("FormSections/_TwoColumnFormSection");
        }
    }


```

### Registering form sections

Register sections by adding the **RegisterFormSection** assembly attribute to the controller class. Specify the following attribute parameters:

- **Identifier** – a _string_ identifier of the form section. We recommend using sufficiently unique identifiers to avoid potential conflicts with other third-party sections, for example using a company name prefix.
- **Controller type** – the _System.Type_ of the form section controller class.
- **Name** – the name of the form section. Displayed when [selecting sections](https://docs.kentico.com/k12sp/managing-website-content/forms/composing-forms.md) on the _Form builder_ tab in the administration interface.
- (Optional) **Description** – a description of the form section. Displayed as a tooltip when selecting sections on the _Form builder_ tab in the administration interface.
- (Optional) **IconClass** – the font-icon assigned to the form section. Displayed when selecting sections on the _Form builder_ tab in the administration interface. For a list of font icons available by default in the system, see [Kentico icon list](http://devnet.kentico.com/docs/icon-list/index.html).

```csharp

using Kentico.Forms.Web.Mvc;

[assembly: RegisterFormSection("LearningKit.FormSections.TwoColumns", typeof(TwoColumnFormSectionController), "Two columns", Description = "Organizes fields into two equal-width columns side-by-side.", IconClass = "icon-l-cols-2")]


```

> **Tip:** **Localizing section metadata**
>
> Both the **Name** and the **Description** of form sections can be localized using resource string keys. See [Localizing MVC builder components](https://docs.kentico.com/k12sp/multilingual-websites/setting-up-a-multilingual-user-interface/localizing-mvc-builder-components.md).

The section is now available in the [form builder interface](https://docs.kentico.com/k12sp/managing-website-content/forms/composing-forms.md).

### Implementing form section views

Create partial views with the required formatting. Use the **FormZone** extension method to identify locations where form fields can be placed.

The recommended location for the view files is the _\~/Views/Shared/FormSections_ folder.

```xml title="Example"

@using Kentico.Forms.Web.Mvc
@using Kentico.Web.Mvc

<div>
    <div style="float:left; width:50%;">
        @Html.Kentico().FormZone()
    </div>
    <div style="float:left; width:50%;">
        @Html.Kentico().FormZone()
    </div>
    <div style="clear:both;" />
</div>

```

## Adding CSS styles for form sections

Use the following approach to add CSS styles for your form sections:

- For **basic styles** that are required for the section to render correctly, create stylesheet files in sub-folders under the  _**\~/Content/FormSections**_  directory of your MVC project (you may need to create the _FormSections_ directory). Use sub-folders that match the identifiers of individual sections.
- If you wish to provide additional styling for the Kentico **administration interface** (for example to ensure that the sections are in line with the overall look and feel of the admin UI), add another stylesheet file to the same directory with the  _**.admin.css**_  extension.
- Any **site-specific styles** that finalize the live site design of the form section should be handled separately within the given site's main stylesheet.

  > **Tip:** To avoid potential conflicts between styles from other third-party form components or sections, we recommend adding a unique prefix to your CSS classes and identifiers (for example _#CompanyName-mid-column_), or employ similar measures to ensure their uniqueness.

The system automatically creates [bundles](https://docs.microsoft.com/en-us/aspnet/mvc/overview/performance/bundling-and-minification) containing all _.css_ files located under _\~/Content/FormSections_ – one for general styles and another for the administration interface styles. The bundles are then linked in the following locations:

- When working with forms in the **Forms** application of the Kentico administration interface.
- The bundle containing general styles is linked on all pages with [page builder editable areas](https://docs.kentico.com/k12sp/developing-websites/page-builder-development/creating-pages-with-editable-areas-in-mvc.md) (the page builder is used to display forms on the live site via the _Form_ widget).

The same bundles also contain styles added for [form components](https://docs.kentico.com/k12sp/developing-websites/form-builder-development/developing-form-components.md) in the _\~/Content/FormComponents_ directory.

> **Note:** **CSS class order**
>
> Do not make any assumptions about the relative order of the source CSS in the resulting bundles – individual files contained in the bundle may or may not precede each other.

## Adding scripts for form sections

If your form sections require any JavaScript, place script files into sub-folders under the  _**\~/Content/FormSections**_  directory of your MVC project (you may need to create the _FormSections_ directory). Use sub-folders that match the identifiers of individual sections or a _Shared_ sub-folder for assets used by multiple sections.

The system automatically creates a [bundle](https://docs.microsoft.com/en-us/aspnet/mvc/overview/performance/bundling-and-minification) containing all _.js_ files located under _\~/Content/FormSections_. The bundle is then linked in the following locations:

- When working with forms in the **Forms** application of the Kentico administration interface.
- On all pages with [page builder editable areas](https://docs.kentico.com/k12sp/developing-websites/page-builder-development/creating-pages-with-editable-areas-in-mvc.md) (the page builder is used to display forms on the live site via the _Form_ widget).

The same bundle also contains script files added for [form components](https://docs.kentico.com/k12sp/developing-websites/form-builder-development/developing-form-components.md) in the _\~/Content/FormComponents_ directory.

### Initializing section scripts

If you need to initialize scripts (for example register an event listener), you can add script tags directly into the view code of your form builder sections. However, you need to keep the following in mind:

- Do not rely on the order of execution of multiple script tags within one section. The order of their execution may be different in the form builder interface than on the live site.
- If you declare variables within section script tags, the variables are defined in the global namespace. To prevent conflicts in forms containing multiple instances of the same section, wrap the scripts into a self-executing anonymous function.
- If you use assets stored in the _\~/Content/FormSections_ folder within the section views, the related bundles are added at the end of the HTML document's body tag. Such assets are not available in the section code during the page load process. A solution is to run the initialization script during the [DOMContentLoaded](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event. However, sections in the form builder interface may be added dynamically after the page is loaded. In this case, the _DOMContentLoaded_ event has already occurred and will not fire again. For example, the following script demonstrates how to reliably call a custom function on page load:

  ```csharp

  @using Kentico.Forms.Web.Mvc
  @using Kentico.Web.Mvc

  <div>
      @Html.Kentico().FormZone()
  </div>
  <script type="text/javascript">
  (function () {
      if (document.readyState === "loading") {
          // Calls the function during the 'DOMContentLoaded' event, after the HTML document has been completely loaded 
          document.addEventListener("DOMContentLoaded", function () {
              customFunction();
          }); 
      } else { 
          // Calls the function directly in cases where the section is rendered dynamically after 'DOMContentLoaded'
          customFunction(); 
      }
  })(); 
  </script>

  ```

Apart from initialization code, avoid linking or executing scripts directly within form section views. This could lead to duplicated scripts for forms that contain multiple instances of the same section, or on pages with multiple forms.

### Using jQuery scripts

By default, Kentico links two system jQuery [bundles](https://docs.microsoft.com/en-us/aspnet/mvc/overview/performance/bundling-and-minification) into the pages of the form builder interface. The system jQuery version is 3.3.1. If you wish to use a different version of jQuery within your form sections, you need to create your own bundle(s) with the corresponding paths:

- _\~/bundles/jquery_
- _\~/bundles/jquery-unobtrusive-ajax_ – bundle for using the [jquery.unobtrusive-ajax.js](https://www.nuget.org/packages/Microsoft.jQuery.Unobtrusive.Ajax/) JavaScript library (not to be confused with the _jquery.validate.unobtrusive.js_ library)

When you register a bundle with one of these paths, the form builder interface links your jQuery bundle instead of the corresponding system bundle.

> **Note:** **Important**: When you register a custom jQuery bundle, the system no longer links the default jQuery bundle on pages with [page builder](https://docs.kentico.com/k12sp/developing-websites/page-builder-development.md) editable areas (the page builder is used to display forms on the live site via the _Form_ widget). You need to manually link your custom jQuery bundle on the given pages (either within the used layout or directly in the page's view).
>
> For more information, see [Creating pages with editable areas in MVC](https://docs.kentico.com/k12sp/developing-websites/page-builder-development/creating-pages-with-editable-areas-in-mvc.md).