---
title: Extend widgets
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/widget-properties.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 extend an existing widget instead of creating a new one from scratch. The API provides a way to render a **"nested"** widget from the view code of another widget. An extended widget retains the full functionality of the original nested widget, but can introduce additions such as wrapping HTML code, new [configurable properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/widget-properties.md) and additional custom logic.

Nesting is possible for widgets of any type, including the [default system widgets](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/reference-default-page-builder-widgets.md), third-party widgets, or your own custom widgets. The only requirement is for the widget to be registered using the RegisterWidget assembly attribute (as described in [Widgets for Page Builder](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder.md)).

> **Info:** **Usage tracking in extended widgets**
>
> The system automatically [tracks content item usage](https://docs.kentico.com/documentation/business-users/content-hub/content-items.md#track-usage-of-content-items) for widget properties that use default form components (e.g., the [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)), including properties inherited from nested widgets. For custom form components that reference content items, you need to implement a custom reference extractor. For more information, see [UI form component reference extractors](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/ui-form-component-reference-extractors.md).
>
> Similarly, the system [tracks form usage](https://docs.kentico.com/documentation/business-users/digital-marketing/forms/create-and-edit-forms.md#track-usage-of-forms) for widget properties that use the [form selector](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/reference-admin-ui-form-components.md#form-selector) component, including properties inherited from nested widgets (e.g., the form selector in the default _Form_ widget). If you use a different form component (such as the [object selector](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/reference-admin-ui-form-components.md#object-selector)) to reference forms, mark the property with the `TrackFormReference` attribute. For more information, see [Assign form reference tracking to Page Builder component properties](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/ui-form-component-reference-extractors.md#assign-form-reference-tracking-to-page-builder-component-properties).

## Creating extended widgets

To create a widget that extends another widget via nesting:

1. Start by following the [standard widget development](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder.md) instructions.
2. For widgets with [configurable properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/widget-properties.md), choose one of the following approaches based on your requirements:

   - Use the property model class of the nested widget for your extended widget (either during registration or in the widget's custom view component).\
     – OR –
   - Create a new property model class that **inherits** from the nested widget's property model. You can then add any properties that you need for your extended widget.
3. In the partial view of the extended widget, find the location where you want to display the content of the nested widget, and call the `Html.Kentico().RenderNestedWidgetAsync` extension method (from the `Kentico.PageBuilder.Web.Mvc` namespace) or its [Tag Helper](https://docs.kentico.com/documentation/developers-and-admins/development/reference-tag-helpers.md) equivalent. The method takes the following parameters:
   - **`identifier`**– the _string_ identifier under which the nested widget was registered. For identifiers of the default system widgets, check [the system widget reference](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/reference-default-page-builder-widgets.md).
   - **`properties`**– object containing the properties of the nested widget. Use the ComponentViewModel model class to make the system automatically pass the [properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/widget-properties.md) to the widget view.

You now have a custom widget that provides the same content and functionality as the nested widget. Implement any required extended functionality, for example by adding HTML code before or after the nested widget.

If the nested widget has configurable properties, they are also available for the extended widget within the Page Builder interface (along with any additional properties defined in an inherited property model class).

## Example

The following example demonstrates how to use widget nesting to extend the system's default **Form** widget. The sample extended widget adds an extra heading above the default form content, along with a custom property that allows editors to set the heading text.

1. Create a widget property model class in the _\~/Components/Widgets/ExtendedFormWidget_ folder, named **ExtendedFormWidgetProperties.cs**.
2. Make the property model inherit from the `FormWidgetProperties` class (in the `Kentico.Forms.Web.Mvc.Wigets` namespace), which is the property model of the default form widget.
3. Define a string property representing the text of the additional heading.

   ```csharp
   using Kentico.Forms.Web.Mvc.Widgets;
   using Kentico.Xperience.Admin.Base.FormAnnotations;

   public class ExtendedFormWidgetProperties : FormWidgetProperties
   {
       // Defines a property and sets its default value
       // Assigns the default Kentico text input component, which allows users to enter
       // a textual value for the property in the widget's configuration dialog
       [TextInputComponent(Order = 0, Label = "Heading text")]
       public string HeadingText { get; set; } = "Default";
   }
   ```
4. Create a partial view for the widget in the _\~/Components/Widgets/ExtendedFormWidget_ folder, named **\_ExtendedFormWidget.cshtml**.
5. Call the `Html.Kentico().RenderNestedWidgetAsync` extension method to render the system's default form widget.

   ```cshtml
   @using Kentico.Content.Web.Mvc
   @using Kentico.PageBuilder.Web.Mvc
   @using Kentico.Web.Mvc

   @model ComponentViewModel<ExtendedFormWidgetProperties>
   @* Configurable heading added above the default form widget *@
   <h1>@Model.Properties.HeadingText</h1>

   @* Renders the nested form widget *@
   @await Html.Kentico().RenderNestedWidgetAsync(SystemComponentIdentifiers.FORM_WIDGET_IDENTIFIER, Model.Properties)
   ```
6. Register the new widget into the system using the `RegisterWidget` assembly attribute. We recommend adding a dedicated file to your project's _\~/Components_ folder for the purposes of component registration, for example named **ComponentRegister.cs**.

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

   // Registers the 'Extended form' widget
   [assembly: RegisterWidget("MySite.Widgets.ExtendedFormWidget",
                             "Extended form",
                             typeof(ExtendedFormWidgetProperties),
                             customViewName: "~/Components/Widgets/ExtendedFormWidget/_ExtendedFormWidget.cshtml",
                             IconClass = "icon-form")]
   ```

You now have a custom widget that works exactly like the default _Form_ widget, but with an additional heading. The text of the heading can be configured in the Page Builder interface through a new property.