Styling UI Components

Manually Migrating Projects to New Theme Versions

Migrating an existing project to the latest versions of the Telerik and Kendo UI themes allows you to transfer your custom theme to a new ThemeBuilder project that enables you to use the latest versions of the Telerik and Kendo UI components.

Understanding the Telerik and Kendo UI Versions

Each custom theme that you create in ThemeBuilder uses a specific version of the Telerik and Kendo UI themes as a base for your customizations. Each version of the Telerik and Kendo UI themes supports a specific version of the Telerik and Kendo UI components. This dependency means that your custom theme supports only the component versions that are supported by the Telerik and Kendo UI theme used as a base theme in your project. For example, if your ThemeBuilder project references version 6.0.3 of the Telerik and Kendo Default theme, the compatible Telerik and Kendo UI components are from the R1 2023 release.

Consider the following specifics related to versioning and matching theme versions with UI component versions:

  • The Telerik and Kendo UI components support only the Telerik and Kendo UI themes from the same release (the components and the themes are released on the same date).
  • The Telerik and Kendo UI components and the Telerik and Kendo UI themes are distributed as different packages and have different versioning.

  • ThemeBuilder displays a badge with the version of the base theme for each ThemeBuilder project. To find the compatible versions of the Telerik and Kendo UI components:

    1. From the toolbar, select the project menu dropdown.
    2. Select the Telerik and Kendo UI Theme Version button.

  • To apply your custom ThemeBuilder theme to a version of the UI components from a later release, you must migrate your custom theme to a new project that uses a base theme from the same release as the target UI components version.

Migrating Your Project

To migrate the customizations from a project that uses a previous version of the Telerik and Kendo UI themes:

  1. Open the project that you want to migrate.

  2. Download the project's metadata:

    1. From the toolbar, select the project menu dropdown.
    2. Select Export Metadata.
    3. Save the downloaded .zip file.

  3. Create a new ThemeBuilder project. Use the same base theme as the project that you migrate.

  4. In the newly created project, upload the metadata of the project that you migrate.

    1. From the toolbar, select the project menu dropdown.
    2. Select Import Metadata.
    3. Upload the .zip file with the metadata of the project that you want to migrate.

  5. If your previous project uses custom fonts, manually add them to your new project.

Users with Free account will have only the Variables imported in the new project.

Exceptions

Occasionally, the developers of the Telerik and Kendo UI themes introduce breaking changes that aim at adding new features and improving the rendering of the UI components. This allows the developers to keep the Telerik and Kendo UI themes in sync with the latest trends.

Breaking changes, however, can block the untroubled migration described in the previous section. Such breaking changes include:

  • Changes in the naming of the Sass variables.
  • Changes in the selectors used in the theme style overrides.

Changed Sass Variables

Version 6.0.0 of the Telerik and Kendo UI themes introduces breaking changes caused by the renaming and removal of multiple Sass variables. Migrating a project to a version of the themes that uses new sass variable names creates custom sass variables for all Kendo variables that you've used in your previous project. ThemeBuilder does this to ensure the successful sass compilation. To solve the migration issue, you can:

  • Manually update the new Kendo sass variables in your new project by taking their values from the respective sass variables in the previous project.

  • Migrate the exported variables as described in the Handling Breaking Changes in Sass Variables article.

Changed Selectors

Specific versions of the Telerik and Kendo UI themes may introduce new names for selected styles. For example, .k-this-style can be renamed to .k-that-style. This leads to compilation errors and adds styles that you cannot change from ThemeBuilder. To solve this issue, follow the steps in the Handling Breaking Changes in the ThemeStyleOverrides article.

In this article
Related articles
Not finding the help you need?