---
title: Transform widget properties
---

> 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 technical deep dive shows you how to transform widget properties during an upgrade from Kentico Xperience 13 (KX13) to Xperience by Kentico (XbyK). You'll learn how to migrate properties that use different UI controls, handle custom components, and enhance the editing experience by restructuring widget properties.

While the [Kentico migration tool](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool) handles most standard widget properties automatically, you often need to customize the migration process when working with complex property configurations or when modernizing widgets as part of the upgrade.

For comprehensive widget restructuring scenarios, see our [Migrate widget data as reusable content](https://docs.kentico.com/modules/upgrade-widget-migration/plan-widget-migration.md) page. This material focuses on property-level transformations.

## Understand the mechanics

Before exploring specific transformation scenarios, it's important to understand how widget property migration works. Generally, upgrading widget properties involves two key aspects: _data migration_ and _code migration_.

**Data migration** handles the transformation of existing widget property data from your KX13 database to the new XbyK structure. Most widget properties are straightforward to handle and migrate automatically as they map one-to-one between KX13 and XbyK (e.g., text fields) or have a default migration defined (e.g., pages, attachments/media files).

> **Info:** See our GitHub documentation for [how different property types map between versions](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.CLI/README.md#migration-details-for-specific-object-types) of our product.

For properties you wish to modify, you need to define your own custom widget property migration. You can do this for properties using out-of-the-box UI controls and custom controls alike.

**Code migration** involves updating your widget property classes to use XbyK's new form component attributes and APIs. When you use [source instance API discovery](https://github.com/Kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.CLI/README.md#source-instance-api-discovery), you'll need to adjust your widget properties to utilize the new controls. This is a straightforward and methodical process, where AI assistance can help – at least for the out-of-the-box UI controls.

If your widgets use any custom UI controls, you'll need to re-implement them in the target solution.

Now let's walk through concrete examples that demonstrate different types of property transformations.