New to Telerik UI for Blazor? Start a free 30-day trial

Breaking Changes in 2.0.0

Updated over 6 months ago

In the 2.0.0 release, there are some changes in the Telerik Blazor components that have been brewing for a while due to the evolution of the framework. This article explains what they are and what you need to change.

A shortlist of the changes:

The component namespaces changed, so now you only need to include @using Telerik.Blazor.Components and @using Telerik.Blazor in your main _Imports.razor file, instead of a per-component statement in each view.
Some inner tags changed names for brevity and usability. A detailed list with the changes per component is available below.
- Most notably, the Telerik prefix is removed from all child tags, only the root-level components are still <TelerikComponentName>. There are some particular changes for certain components, and they are detailed below.
Some methods that manipulated collections or state are now gone. The way to alter collections (like Action buttons on a Window) is to use conditional markup and looping over collections from a view model. When we were initially creating the components, there were indications that there will be programmatic creation options. It seems this is not going to be the case, and conditional markup plus binding is the way to affect markup. There are details for each component below.
The Window renders at the root of the app.

In case the lists in this article do not suffice, you can go to the concrete component's demos and documentation to see the way it is to be used after these changes. The documentation always reflects the latest version of our components.

Namespace Change
Removed Methods and Properties
Renamed Tags

Namespace Change

Until now, you had to include things like @using Telerik.Blazor.Components.<ComponentName> for every component use used, in every view.

As of the 2.0.0 version, you only need to add the following to your main ~/_Imports.razor file, and you have to remove the @using statements per component:

RAZOR

@using Telerik.Blazor
@using Telerik.Blazor.Components

You can keep @using Telerik.Blazor.Components in the views, it simply is not needed anymore.

Moved Enums

Some enums had to move to different namespaces and/or to have more descriptive names:

Razor

// Chart
Telerik.Blazor.ChartSeriesStack -> Telerik.Blazor.ChartSeriesStackType

// Grid
Telerik.Blazor.FilterMode -> Telerik.Blazor.GridFilterMode

// TabStrip
Telerik.Blazor.Components.TabStrip.TabPosition -> Telerik.Blazor.TabPosition

// Window
Telerik.Blazor.Size -> Telerik.Blazor.WindowSize

Removed Methods and Properties

This is a list of the components that had methods removed and the new approach of doing things.

Button

The IsIconButton property is removed. It was never supposed to be public and is set internally by the component when it has no text.

Calendar

The Navigate() method is no longer available in favor of two-way binding for the View and Date parameters. An example is available in the Navigate article.
The View and Date parameters should be used with two-way binding, especially when you handle ValueChanged. Otherwise, state changes (like selection) may revert them to the values set in the markup and move the user unexpectedly.

DatePicker

The Close() method is no longer available. The popup closes on clicks outside of it anyway.

Icon

The standalone icon component is now in the Telerik.Blazor.Components.Common.Icon namespace.
The IconName property is now Icon.
The Class property is now IconClass.
If you want to use the Telerik icons together with custom classes, you must amend those classes instead of using the Icon property. For example, <TelerikIcon IconClass="@("my-class k-icon k-i-" + IconName.File )" />.

Grid

The AddColumn() and RemoveColumn() methods are removed. Use conditional markup instead, like in the Columns demo.
The Filterable property is removed in favor of FilterMode.
The EditMode property is now an enum. Use EditMode="@GridEditMode.Incell|Inline|Popup".

Inputs

All input-type components (DropDownList, DateInput, DatePicker, etc.) no longer have the Height property. Their height is to be controlled through CSS and the font-size through the themes anyway, and the Height property did not always produce expected/proper results.

TabStrip

The ActivateTab() and DeactivateTab() methods are no longer available. Use the new ActiveTabIndex property and its ActiveTabIndexChanged event.
The AddTab() method is no longer available in favor of conditional markup.

Textbox

The Pattern, MinLength and MaxLength parameters are removed in favor of validation.

TreeView

The AddBinding() and RemoveBinding() methods are no longer available.

Window

The Open(), Close(), Minimize(), Maximize(), Restore() methods are removed in favor of parameter binding - for the Visible parameter and the new State parameter.
The Minimized and Maximized parameters are removed in favor of the State parameter.
The AddAction(), RemoveAction() methods are removed in favor of conditional markup.
The window renders at the root of the app and not in place. Thus, its position is relative to the root and maximizing fills it up, instead of the closest parent with special positioning. This also applies to the Top and Left offsets - they are now relative to the app root as well.

Renamed Tags

This is a list of the components that had their child tags removed or renamed.

Chart

All child tags that had Telerik as a prefix do not have that prefix anymore.

DropDownList

Header is now HeaderTemplate
Footer is now FooterTemplate

RAZOR

// Old
<TelerikDropDownList Data="@Data">
    <Header></Header>
    <Footer></Footer>
    <ValueTemplate></ValueTemplate>
    <ItemTemplate></ItemTemplate>
</TelerikDropDownList>

// New
<TelerikDropDownList Data="@Data">
    <HeaderTemplate></HeaderTemplate>
    <FooterTemplate></FooterTemplate>
    <ValueTemplate></ValueTemplate>
    <ItemTemplate></ItemTemplate>
</TelerikDropDownList>

Grid

The TelerikGridEvents and EventsManager tags are removed. The CRUD events of the grid are now available at its root-level tag, for example <TelerikGrid OnRead=@ReadItems>.
All child tags that had Telerik as a prefix do not have that prefix anymore.

RAZOR

// Old
<TelerikGrid Data=@GridData>
    <TelerikGridColumns>
        <TelerikGridCommandColumn>
            <TelerikGridCommandButton>Edit</TelerikGridCommandButton>
        </TelerikGridCommandColumn>
        <TelerikGridColumn>
            <Template>
                <p>content</p>
            </Template>
        </GridColumn>
    </TelerikGridColumns>
    <TelerikGridToolBar>
        <TelerikGridCommandButton>Text</TelerikGridCommandButton>
    </TelerikGridToolBar>
    <RowTemplate>
        <p>content</p>
    </RowTemplate>
    <TelerikGridEvents>
        <EventsManager OnUpdate=@UpdateItem></EventsManager>
    </TelerikGridEvents>
</TelerikGrid>

// New
<TelerikGrid Data=@GridData OnUpdate=@UpdateItem>
    <GridColumns>
        <GridCommandColumn Command="save">
            <GridCommandButton>Edit</GridCommandButton>
        </GridCommandColumn>
        <GridColumn>
            <Template>
                <p>content</p>
            </Template>
        </GridColumn>
    </GridColumns>
    <GridToolBar>
        <GridCommandButton>Text</GridCommandButton>
    </GridToolBar>
    <RowTemplate>
        <p>content</p>
    </RowTemplate>
</TelerikGrid>

TabStrip

TelerikTab is now TabStripTab

RAZOR

// Old
<TelerikTabStrip>
    <TelerikTab>
        <p>tab content</p>
    </TelerikTab>
</TelerikTabStrip>

// New
<TelerikTabStrip>
    <TabStripTab>
        <p>tab content</p>
    </TabStripTab>
</TelerikTabStrip>

TreeView

All child tags that had Telerik as a prefix do not have that prefix anymore.

RAZOR

// Old
<TelerikTreeView Data="@HierarchicalData">
    <TelerikTreeViewBindings>
        <TelerikTreeViewBinding>
            <ItemTemplate>
                <p>content</p>
            </ItemTemplate>
        </TelerikTreeViewBinding>
    </TelerikTreeViewBindings>
</TelerikTreeView>

// New
<TelerikTreeView Data="@HierarchicalData">
    <TreeViewBindings>
        <TreeViewBinding>
            <ItemTemplate>
                <p>content</p>
            </ItemTemplate>
        </TreeViewBinding>
    </TreeViewBindings>
</TelerikTreeView>

Window

All child tags that had Telerik as a prefix do not have that prefix anymore.

RAZOR

// Old
<TelerikWindow>
    <TelerikWindowTitle>
        <p>Title</p>
    </TelerikWindowTitle>
    <TelerikWindowActions>
        <TelerikWindowAction Name="Minimize"></TelerikWindowAction>
    </TelerikWindowActions>
    <TelerikWindowContent>
        <p>content</p>
    </TelerikWindowContent>
</TelerikWindow>

// New
<TelerikWindow>
    <WindowTitle>
        <p>Title</p>
    </WindowTitle>
    <WindowActions>
        <WindowAction Name="Minimize"></WindowAction>
    </WindowActions>
    <WindowContent>
        <p>content</p>
    </WindowContent>
</TelerikWindow>