---
title: Widget properties
related:
  - https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder.md
  - https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder.md
  - https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/inline-editors-for-widget-properties.md
  - https://docs.kentico.com/documentation/business-users/website-content/widgets-and-page-builder.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 widgets](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder.md), you can define properties that allow content editors to adjust the widget content or behavior directly in the administration interface. Users interact with widget properties through the widget configuration dialog or inline editors, which you need to implement.

Use the following process to develop properties for a widget:

1. [Create a model class that defines the widget properties](#create-property-models).
2. Allow content editors to modify the widget properties:
   - [Define the configuration dialog](#define-the-configuration-dialog)
   - [Implement inline editors](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/inline-editors-for-widget-properties.md)

> **Tip:** **Configuration dialog and inline editors**
>
> You can combine the configuration dialog and inline editors in a single widget.

3. [Handle the properties in the widget's code](#handle-properties-in-widget-code).
4. (Optional) [Add support for POST actions](#access-widget-properties-in-post-actions).

To see a scenario with full code samples that guides you through the process of developing a simple widget with a property, visit [Example - Widget development](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/example-widget-development.md). For a detailed walkthrough showing how to create a more complex widget, see the [Define an advanced widget](https://docs.kentico.com/guides/development/page-builder/define-advanced-widget.md) guide.

> **Note:** **Areas**
>
> Widgets are designed as global components. Adding related files, such as property model classes, into Areas is not supported and may lead to unexpected behavior.

## Create property models

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

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

```csharp
using Kentico.PageBuilder.Web.Mvc;

public class CustomWidgetProperties : IWidgetProperties
{
    // Defines a property and sets its default value
    public int Number { get; set; } = 22;
}
```

> **Tip:** You can use the `Newtonsoft.Json.JsonIgnore` attribute to exclude dynamically computed widget properties from database serialization.

We recommend storing widget property models in the _\~/Components/Widgets/\<widget name>_ folder together with other files required by the widget.

## Define the configuration dialog

The configuration dialog is a simple way to allow content editors to set values for widget properties. In the property model class, you need to define editing form components for widget properties that you want to make editable in the configuration dialog. You can use the system's [default form components](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/reference-admin-ui-form-components.md) or develop [custom form components](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components.md).

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

   - Assign [editing components](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/editing-components.md) to desired properties.

     ```csharp
     using Kentico.Xperience.Admin.Base.FormAnnotations;

     // ...

     [TextInputComponent(Order = 0, Label = "Text")]
     public string Text { get; set; }
     ```

   - To store labels and other texts of editing components in resource files, use [localization expressions](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/localize-custom-admin-code.md#localization-expressions). Register the resource file for `LocalizationTarget.Builder` under the [culture codes](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization.md#culture-codes) of your admin UI languages, and the English strings under the `SystemContext.SYSTEM_CULTURE_NAME` constant. A culture code that doesn't match exactly fails without an error. For example, strings registered under `es` don't resolve for `es-ES` editors, who see the English strings instead. English strings registered under `en` instead of the `SystemContext.SYSTEM_CULTURE_NAME` constant don't resolve either, so editors see the resource keys. See [Register builder resources](https://docs.kentico.com/documentation/developers-and-admins/customization/admin-ui-localization/localize-builder-components.md#register-builder-resources).

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

> **Warning:** **Custom editing components with links to content items and pages**
>
> If you decorate any widget property with a [custom form component](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components.md) or use an [inline editor](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/inline-editors-for-widget-properties.md) that allows users to add links to content items and pages (other than the default [combined content selector](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/reference-admin-ui-form-components.md#combined-content-selector), [page selector](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/reference-admin-ui-form-components.md#page-selector) and [rich text editor](https://docs.kentico.com/documentation/business-users/rich-text-editor.md)), you need to create a [custom reference extractor](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/ui-form-component-reference-extractors.md) in order to enable [usage tracking](https://docs.kentico.com/documentation/business-users/content-hub/content-items.md#track-usage-of-content-items) in the widget property.

> **Tip:** **Advanced property options**
>
> You can add dynamic [visibility conditions and validation](https://docs.kentico.com/documentation/developers-and-admins/development/builders/builder-component-properties-visibility-and-validation.md) that restrict how and when properties are displayed in the widget configuration dialog.

## Handle properties in widget code

For properties to have an effect on a widget's appearance or functionality, you need to retrieve their values and reflect them in the widget's output code or logic. The required steps depend on the development approach used to create the widget (see [Widgets for Page Builder](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder.md) for more information).

### Basic widgets

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

The view must use the generic `ComponentViewModel<TPropertyModel>` class as its model, with the appropriate property model class as the generic type parameter. The system ensures that property values configured for the currently processed widget 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.

```cshtml title="Example"
@using Kentico.PageBuilder.Web.Mvc

@model ComponentViewModel<CustomWidgetProperties>

<p>The value of the widget's 'Number' property is: @Model.Properties.Number</p>
```

### Widgets based on a view component

To work with widget properties in view components, the component's `Invoke` or `InvokeAsync` method signature must declare the `ComponentViewModel<TPropertiesType>` parameter, with the appropriate property model class as the generic type.

```csharp
// The signature of a view component's InvokeAsync method for widgets with custom properties
public Task<IViewComponentResult> InvokeAsync(ComponentViewModel<CustomWidgetProperties> widgetProperties)
```

The widget's properties are accessible via the Properties property of the ComponentViewModel parameter, which contains an object of the specified property model class. The property values are loaded from the current configuration of the processed widget.

```csharp
// Gets the value of a widget property from within a component's Invoke method
int propertyValue = widgetProperties.Properties.Number;
```

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

> **Info:** Do not directly pass the property model to your widget views. Passing data to views is the responsibility of the widget's view model. For this reason, we strongly recommend keeping the models separate.

## Enable AI content marking

Widgets can support [AI content marking](https://docs.kentico.com/documentation/business-users/aira.md#ai-content-marking), which records whether the content of a widget property was generated or modified by AI. To enable the marking, inherit the widget's property model class from `AiProvenanceWidgetProperties` (available in the `Kentico.Builder.Web.Mvc` namespace).

```csharp title="CustomWidgetProperties.cs"
using Kentico.Builder.Web.Mvc;
using Kentico.PageBuilder.Web.Mvc;
using Kentico.Xperience.Admin.Base.FormAnnotations;

// Enables AI content marking for the widget's properties
public class CustomWidgetProperties : AiProvenanceWidgetProperties, IWidgetProperties
{
    [TextAreaComponent(Order = 0, Label = "Text")]
    public string Text { get; set; }
}
```

Content editors can then mark properties that use the _Text input_, _Text area_, or _Rich text editor_ form component in the [configuration dialog](#define-the-configuration-dialog). To enable the marking for custom form components, see [Enable AI content marking](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components.md#enable-ai-content-marking).

The widget header offers the marking only for the content of the system _Rich text_ widget. Properties of custom widgets edited through [inline editors](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/inline-editors-for-widget-properties.md) can't be marked in the administration interface.

AIRA [rich text refinements](https://docs.kentico.com/documentation/business-users/aira.md#rich-text-editor-refinements) mark the refined property automatically, except for _Improve spelling and grammar_. The system _Rich text_ widget supports the marking by default.

To read the marking when rendering the widget, call `GetAiProvenanceOrigin` on the property model with the name of the property. The method returns `AiProvenanceOrigin.None` for properties without a marking.

```cshtml title="_CustomWidget.cshtml"
@using CMS.ContentEngine
@using Kentico.PageBuilder.Web.Mvc

@model ComponentViewModel<CustomWidgetProperties>

@{
    // Gets the AI origin of the widget's 'Text' property
    AiProvenanceOrigin textOrigin = Model.Properties.GetAiProvenanceOrigin(nameof(CustomWidgetProperties.Text));
}

@if (textOrigin != AiProvenanceOrigin.None)
{
    <p class="ai-label">
        @(textOrigin == AiProvenanceOrigin.AiGenerated ? "AI generated" : "AI modified")
    </p>
}
<p>@Model.Properties.Text</p>
```

See [Display AI content labels](https://docs.kentico.com/documentation/developers-and-admins/configuration/aira-configuration/display-ai-content-labels.md) for more information about AI content labels.

## Access widget properties in POST actions

Basic POST requests do not by default contain widget properties data. To access the properties of a widget during POST actions (in the [class](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder.md) handling POST requests), you first need to include the properties into the data submitted by the corresponding HTML form in the widget's output. Call the `Html.Kentico().ComponentPropertiesData` extension method (or its [Tag Helper](https://docs.kentico.com/documentation/developers-and-admins/development/reference-tag-helpers.md) equivalent) within the given form tag in your widget view.

```cshtml title="Example"
using Kentico.Content.Web.Mvc

...

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

    @Html.Kentico().ComponentPropertiesData()

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

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

On the server, access the widget's properties in the corresponding controller class via the `IPageBuilderComponentPropertiesRetriever` service and its `Retrieve<TWidgetProperties>` method. Specify the widget's properties class as the method's generic parameter:

```csharp title="Controller class handling the request"
using Kentico.PageBuilder.Web.Mvc;

using Microsoft.AspNetCore.Mvc;

public class WidgetPostController(
    IPageBuilderComponentPropertiesRetriever componentPropertiesRetriever) : Controller
{
    [HttpPost]
    public async Task<IActionResult> HandlePost()
    {
        // Gets the properties of the widget as a strongly typed object
        NumberWidgetProperties properties = componentPropertiesRetriever.Retrieve<NumberWidgetProperties>();

        // Use the properties to perform some action
        // ...
    }
}
```