---
title: Defining section properties
related:
  - https://docs.kentico.com/13/developing-websites/page-builder-development.md
  - https://docs.kentico.com/13/developing-websites/page-builder-development/creating-pages-with-editable-areas.md
  - https://docs.kentico.com/13/developing-websites/page-builder-development/developing-page-builder-sections.md
  - https://docs.kentico.com/13/multilingual-websites/setting-up-a-multilingual-user-interface/localizing-builder-components.md
  - https://docs.kentico.com/13/managing-website-content/adding-page-content-using-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).

When developing [page builder sections](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-page-builder-sections.md), you can define properties that allow content editors to adjust the appearance or behavior of the sections in the administration interface. Users then interact with the section properties through section configuration dialogs.

Use the following process to develop properties for a section:

1. [Create a model class that defines the section properties](#creating-property-models)
2. [Define the configuration dialog to allow content editors to modify the properties](#defining-the-configuration-dialog)
3. [Handle the properties in the section's code](#handling-properties-in-section-code)

See the [Example](#example---developing-a-section-with-a-configurable-property) on this page for a scenario with full code samples.

## Creating property models

The properties of a section must be defined within a model class that implements the **ISectionProperties** interface (available in the **Kentico.PageBuilder.Web.Mvc** namespace).

Specify each section property by creating a corresponding property in the model class. You can also set default values for the properties.

```csharp title="Example"

public class CustomSectionProperties : ISectionProperties
{
    // Defines a property and sets its default value
    public string Color{ get; set; } = "#FFF";
}

```

> **Tip:** You can use the _Newtonsoft.Json.JsonIgnore_ attribute to exclude dynamically computed section properties from database serialization.

<!-- dev-model:mvc start -->

**MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block.

We recommend storing section property models in the _\~/Models/Sections/_ folder.

<!-- dev-model:mvc end -->

<!-- dev-model:core start -->

**ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block.

We recommend storing section property models in a dedicated __ folder together with other files required by the section.

<!-- dev-model:core end -->

## Defining the configuration dialog

The configuration dialog is a simple way to allow content editors to set values for section properties. In the property model class, you need to define editing form components for section properties which you want to make editable in the configuration dialog. You can use the system's [default form components](https://docs.kentico.com/13/developing-websites/form-builder-development/reference-system-form-components.md) or develop [custom form components](https://docs.kentico.com/13/developing-websites/form-builder-development/developing-form-components.md).

1. Edit the section's property model class in your live site project.
2. Define the visual interface of the configuration dialog:

   - Decorate the appropriate properties using the **EditingComponent** attribute (available in the _Kentico.Forms.Web.Mvc_ namespace).
   - The attribute assigns and configures a [form component](https://docs.kentico.com/13/developing-websites/form-builder-development/reference-system-form-components.md), which is used as the input element for the given property in the configuration dialog.

     > **Note:** **Note**: To learn about the available options when using and configuring editing components for properties, see [Assigning editing components to properties](https://docs.kentico.com/13/developing-websites/form-builder-development/assigning-editing-components-to-properties.md).

```csharp title="Example - Setting an editing component"

[EditingComponent(TextInputComponent.IDENTIFIER, Order = 0, Label = "Color")]
public string Color { get; set; } = "#FFF";

```

Users can now click the **Configure** () icon when [working with sections in the administration interface](https://docs.kentico.com/13/managing-website-content/adding-page-content-using-widgets.md). This opens the section properties dialog, and the configured property values affect the appearance and functionality of the section on the live site.

> **Tip:** **Advanced property options**
>
> - You can add dynamic [visibility conditions](https://docs.kentico.com/13/developing-websites/form-builder-development/adding-visibility-conditions-for-builder-component-properties.md) that restrict how and when properties are displayed in the section configuration dialog.
> - If you need to create advanced property editors, you can implement [modal dialogs](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-modal-dialogs-for-builder-component-properties.md). This allows users to set the section property's value in a custom dialog (a new window separate from the configuration dialog).

## Handling properties in section code

In order for properties to have an effect on a section's appearance or functionality, you need to retrieve the property values and adjust the section's output code or logic correspondingly. The required steps depend on the development approach used to create the section (see [Developing page builder sections](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-page-builder-sections.md) for more information).

<!-- dev-model:mvc start -->

**MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block.

### Basic sections

For sections without a custom controller class, handle the property values in the section's partial view.

The view must use the generic **ComponentViewModel** class as its model, with the appropriate property model class as the generic type parameter. The system's default controller ensures that the property values configured for the currently processed section are passed to the view. Retrieve the property values from the model's **Properties** member, which returns an object of the specified property model class.

```xml title="Example"

@using Kentico.PageBuilder.Web.Mvc
@using Kentico.Web.Mvc

@model ComponentViewModel<CustomSectionProperties>

<div style="background-color: @Model.Properties.Color;">
    @Html.Kentico().WidgetZone()
</div>

```

### Sections with a custom controller

To work with properties in your section controllers, the controller class must inherit from the generic **SectionController** base class, with the appropriate property model class as the generic type parameter.

```csharp

public class CustomSectionController : SectionController<CustomSectionProperties>


```

Retrieve the properties as a strongly typed object via the **IComponentPropertiesRetriever** service (_Kentico.PageBuilder.Web.Mvc_ namespace) and its **Retrieve** method. The method returns an object of the specified property model class. The object's property values are loaded from the current configuration of the processed section.

```csharp

// Contains an instance of the IComponentPropertiesRetriever service. For example, obtained via dependency injection.
private readonly IComponentPropertiesRetriever componentPropertiesRetriever;

// Gets the value of a section property (e.g. within the Index action of the section's controller)
CustomSectionProperties properties = componentPropertiesRetriever.Retrieve<CustomSectionProperties>();
string propertyValue = properties.Color;

```

You can then adjust the code of your controller based on the values of individual section properties, or pass them to the section's view using an appropriate view model.

> **Info:** Do not directly pass the property model to your section views. We strongly recommend creating a separate view model class, which you can then use to pass data to the section view.

<!-- dev-model:mvc end -->

<!-- dev-model:core start -->

**ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block.

### Basic sections

For basic sections that consist only of a partial view file and a properties class, handle the property values in the section's partial view.

The view must use the generic **ComponentViewModel** class as its model, with the appropriate property model class as the generic type parameter. The system ensures that the property values configured for the currently processed section are passed to the view. Retrieve the property values from the model's **Properties** member, which returns an object of the specified property model class.

```xml

@addTagHelper Kentico.Content.Web.Mvc.WidgetZoneTagHelper, Kentico.Content.Web.Mvc

@using Kentico.PageBuilder.Web.Mvc

@model ComponentViewModel<CustomSectionProperties>

@* Shows a sample section with a background color specified in the section's configuration dialog *@
<div style="background-color: @Model.Properties.Color;">
    @* Renders a widget zone via the widget-zone Tag Helper *@
    <widget-zone />
</div>

```

### Sections based on a view component

To work with properties in your section view components, the component's _Invoke_ or _InvokeAsync_ method signature must declare the **ComponentViewModel** parameter, with the appropriate property model class as the generic type.

```csharp

// The signature of a view component's InvokeAsync method for sections with custom properties
public Task<IViewComponentResult> InvokeAsync(ComponentViewModel<CustomSectionProperties> sectionProperties)


```

The section's properties are accessible via the **Properties** property of the _ComponentViewModel_ parameter. The method returns an object of the specified property model class. The object's property values are loaded from the current configuration of the processed section.

```csharp

// Gets the value of a section property from within a component's Invoke method
var propertyValue = sectionProperties.Properties.BackgroundColor;

```

You can then adjust the flow of your code based on the values of individual section properties, or pass them to the section's view using an appropriate view model.

> **Info:** Do not directly pass the property model to your section views. We strongly recommend creating a separate view model class, which you can then use to pass data to the section view.

<!-- dev-model:core end -->

## Accessing section properties in POST actions

<!-- dev-model:mvc start -->

**MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block.

Section properties cannot be by default retrieved during POST requests. Such requests lack the context of the current page and section instance.

To retrieve section properties in POST actions, you first need to include the properties into the data submitted by the corresponding HTML form in the section's output. Call the **Html.Kentico().ComponentPropertiesData** extension method within the given form tag in your section view.

```csharp title="Example"

using System.Web.Mvc.Ajax
using Kentico.Web.Mvc
using Kentico.PageBuilder.Web.Mvc

...

@using (Ajax.BeginForm("PostAction", "CustomSection", null, new AjaxOptions
{
    HttpMethod = "POST",
    UpdateTargetId = "sectionForm"
}, new { id = "sectionForm" }))
{
    @Html.Kentico().AntiForgeryToken()
    @Html.Kentico().ComponentPropertiesData()
    ...
    <input type="submit" value="Submit" />
}

```

The method renders a hidden field that persists the section's properties and makes them available via the properties retriever in controller actions.

<!-- dev-model:mvc end -->

<!-- dev-model:core start -->

**ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block.

Basic POST requests do not by default contain section properties data. To access the properties of a section during POST actions (in the [controller class](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-page-builder-sections.md#handling-post-actions) handling POST requests), you first need to include the properties into the data submitted by the corresponding HTML form in the section's output. Call the **Html.Kentico().ComponentPropertiesData** extension method (or its [Tag Helper](https://docs.kentico.com/13/developing-websites/developing-xperience-applications-using-asp-net-core/reference-xperience-tag-helpers.md) equivalent) within the given form tag in your section view.

```xml title="Example"

using Kentico.Content.Web.Mvc

...

<form asp-controller="SectionPostController" asp-action="HandlePost" method="post">
    ...

    @Html.Kentico().ComponentPropertiesData()

    <input type="submit" value="Submit" />
</form>

```

The method renders a hidden field that persists the section's current properties configuration.

On the server, access the section's properties in the corresponding controller class via the **IComponentPropertiesRetriever** service and its **Retrieve** method. Specify the section's properties class as the method's generic parameter:

```csharp title="Controller class handling the request"

// Contains an instance of the IComponentPropertiesRetriever service (e.g., obtained via dependency injection)
private readonly IComponentPropertiesRetriever componentPropertiesRetriever;

// Gets the properties of the section as a strongly typed object 
MySectionProperties properties = componentPropertiesRetriever.Retrieve<MySectionProperties>();

```

<!-- dev-model:core end -->

## Example - Developing a section with a configurable property

<!-- dev-model:mvc start -->

**MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block.

The following scenario will guide you through a step-by-step process of developing a simple [page builder section](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-page-builder-sections.md) with a configurable property.

When finished, the section is displayed with a color background of your choice. The color is set via a section property and can be modified through a section configuration dialog. The color can be specified in any text format that is accepted by the [CSS background-color property](https://www.w3schools.com/cssref/pr_background-color.asp) (e.g. a HEX or RGB value).

> **Note:** **Note**: The following example is based on the [LearningKit project](https://github.com/Kentico/LearningKit-Mvc). To use the code samples in your project, you need to modify the namespaces, identifiers and other occurrences where _LearningKit_ is mentioned to match your project's name.

### Property model

Create a properties model **CustomSectionProperties.cs** in the _\~/Models/Sections/CustomSection_ folder:

```csharp

using Kentico.Forms.Web.Mvc;
using Kentico.PageBuilder.Web.Mvc;

namespace LearningKit.Models.Sections.CustomSection
{
    public class CustomSectionProperties : ISectionProperties
    {
        // Defines a property and sets its default value
        // Assigns the default Xperience text input component, which allows users to enter
        // a string value for the property in the section's configuration dialog
        [EditingComponent(TextInputComponent.IDENTIFIER, Order = 0, Label = "Color")]
        public string Color { get; set; } = "#FFF";

    }
}

```

### Partial view

Create a partial view **\_CustomSection.cshtml** in the _\~/Views/Shared/Sections_ folder:

```csharp

@using Kentico.PageBuilder.Web.Mvc
@using Kentico.Web.Mvc

@using LearningKit.Models.Sections.CustomSection

@model ComponentViewModel<CustomSectionProperties>

@* Shows a sample section with a background color specified in the section's configuration dialog *@
<div style="background-color: @Model.Properties.Color;">
    @Html.Kentico().WidgetZone()
</div>

```

### Section registration

Register the section into the system using the **RegisterSection** assembly attribute. We recommend adding a dedicated code file to your project's _\~/App\_Start_ folder for the purposes of component registration, for example named **PageBuilderComponentRegister.cs**.

```csharp

using LearningKit.Models.Sections.CustomSection;

using Kentico.PageBuilder.Web.Mvc;

// Registers the 'Custom section' section (it uses the system's default controller and ComponentViewModel)
[assembly: RegisterSection("LearningKit.Sections.CustomSection",
                          "Custom section",
                          typeof(CustomSectionProperties),
                          customViewName: "Sections/_CustomSection",
                          IconClass = "icon-square")]

```

<!-- dev-model:mvc end -->

<!-- dev-model:core start -->

**ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block.

The following section will guide you through a step-by-step process of developing a simple [page builder section](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-page-builder-sections.md) with a configurable property.

When finished, the section is displayed with a color background of your choice. The color is set via a section property and can be modified through a section configuration dialog. The color can be specified in any text format that is accepted by the [CSS background-color property](https://www.w3schools.com/cssref/pr_background-color.asp) (e.g. a HEX or RGB value).

> **Note:** **Note**: The following example is based on the [LearningKit project](https://github.com/Kentico/LearningKit-Core). To use the code samples in your project, you need to modify the namespaces, identifiers and other occurrences where _LearningKit_ is mentioned to match your project's name.

### Property model

Create a properties model **CustomSectionProperties.cs** in the _\~/Components/PageBuilder/Sections/CustomSection_ folder:

```csharp

using Kentico.Forms.Web.Mvc;
using Kentico.PageBuilder.Web.Mvc;

public class CustomSectionProperties : ISectionProperties
{
    // Defines a property and sets its default value
    // Assigns the default Xperience text input component, which allows users to enter
    // a string value for the property in the section's configuration dialog
    [EditingComponent(TextInputComponent.IDENTIFIER, Order = 0, Label = "Color")]
    public string Color { get; set; } = "#FFF";
}

```

### Partial view

Create a partial view **\_CustomSection.cshtml** in the _\~/Components/PageBuilder/Sections/CustomSection_ folder:

```csharp

@addTagHelper Kentico.Content.Web.Mvc.WidgetZoneTagHelper, Kentico.Content.Web.Mvc

@using Kentico.PageBuilder.Web.Mvc

@model ComponentViewModel<CustomSectionProperties>

@* Shows a sample section with a background color specified in the section's configuration dialog *@
<div style="background-color: @Model.Properties.Color;">
    @* Renders a widget zone via the widget-zone Tag Helper *@
    <widget-zone />
</div>

```

### Section registration

Register the section into the system using the **RegisterSection** assembly attribute. We recommend adding a dedicated code file to your project for the purposes of component registration, for example named **ComponentRegister.cs**.

```csharp

[assembly: RegisterSection("MyCompany.Sections.CustomSection",
                          "Custom section",
                          typeof(CustomSectionProperties),
                          customViewName: "~/Components/PageBuilder/Sections/CustomSection/_CustomSection.cshtml",
                          IconClass = "icon-square")]


```

<!-- dev-model:core end -->