# Migrating to the New .NET MAUI Charts

The new Telerik UI for .NET MAUI Charts are built from the ground up to keep the familiar concepts—`RadCartesianChart`, `RadPieChart`, series, and axes—but expose a new namespace, simplified data binding, updated series, and axes properties.

The new charts provide better performance, improved rendering, and a more consistent API across all chart types.

This article lists the differences between the Telerik MAUI Chart (implemented in the `Telerik.Maui.Controls.Compatibility.Chart` namespace) and the new Charts (implemented in the `Telerik.Maui.Controls.Charts` namespace), so you can update existing applications.

## Data Binding

Both the previous and the new charts populate their series through the `ItemsSource` property. The main difference is how each data point resolves its value and category.

The Compatibility Chart uses `DataPointBinding` objects (`PropertyNameDataPointBinding`) assigned to the `ValueBinding` and `CategoryBinding` properties. The new Charts replace these with the simpler `string`-based `HorizontalBinding` and `VerticalBinding` properties that directly point to the data-item member.

| Chart (`Telerik.Maui.Controls.Compatibility`)           | Charts (`Telerik.Maui.Controls.Charts`)       |
| ------------------------------------------------------- | --------------------------------------------- |
| `ItemsSource` (`IEnumerable`)                           | `ItemsSource` (`IEnumerable`)                 |
| `CategoryBinding` (`DataPointBinding`)                  | `HorizontalBinding` (`string`)                |
| `ValueBinding` (`DataPointBinding`)                     | `VerticalBinding` (`string`)                  |
| `PropertyNameDataPointBinding { PropertyName = "..." }` | Property name assigned directly as a `string` |

> caption Chart (Telerik.Maui.Controls.Compatibility):

```XAML
<telerik:RadCartesianChart>
    <telerik:RadCartesianChart.BindingContext>
        <local:ViewModel />
    </telerik:RadCartesianChart.BindingContext>
    <telerik:RadCartesianChart.HorizontalAxis>
        <telerik:CategoricalAxis />
    </telerik:RadCartesianChart.HorizontalAxis>
    <telerik:RadCartesianChart.VerticalAxis>
        <telerik:NumericalAxis />
    </telerik:RadCartesianChart.VerticalAxis>
    <telerik:RadCartesianChart.Series>
        <telerik:BarSeries CategoryBinding="Category"
                           ValueBinding="Value"
                           ItemsSource="{Binding Data}" />
    </telerik:RadCartesianChart.Series>
</telerik:RadCartesianChart>
```

> caption Charts (Telerik.Maui.Controls.Charts):

```XAML
<charts:RadCartesianChart>
    <charts:RadCartesianChart.BindingContext>
        <models:CategoricalViewModel />
    </charts:RadCartesianChart.BindingContext>
    <charts:RadCartesianChart.Axes>
        <charts:CategoricalAxis />
        <charts:NumericalAxis />
    </charts:RadCartesianChart.Axes>
    <charts:RadCartesianChart.Series>
        <charts:BarSeries HorizontalBinding="Category"
                          VerticalBinding="Value"
                          ItemsSource="{Binding Data}" />
    </charts:RadCartesianChart.Series>
</charts:RadCartesianChart>
```

For more details, see the [Getting Started](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/getting-started) article.

## Namespaces

The namespaces and assembly references for the new Charts have changed. The following table lists the previous and new namespaces.

| Chart (Telerik.Maui.Controls.Compatibility)                 | Charts (Telerik.Maui.Controls.Charts)                                                      |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `xmlns:telerik="http://schemas.telerik.com/2022/xaml/maui"` | `xmlns:charts="clr-namespace:Telerik.Maui.Controls.Charts;assembly=Telerik.Maui.Controls"` |
| `using Telerik.Maui.Controls.Compatibility.Chart;`          | `using Telerik.Maui.Controls.Charts;`                                                      |

In both versions, register the Telerik controls through the `Telerik.Maui.Controls.Compatibility.UseTelerik` extension method inside the `CreateMauiApp` method of the `MauiProgram.cs` file:

```C#
using Telerik.Maui.Controls.Compatibility;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseTelerik()
            .UseMauiApp<App>();
        return builder.Build();
    }
}
```

## Chart Types

Both versions provide the same chart types. The control classes keep their names.

| Chart (Telerik.Maui.Controls.Compatibility) | Charts (Telerik.Maui.Controls.Charts) |
| ------------------------------------------- | ------------------------------------- |
| `RadCartesianChart`                         | `RadCartesianChart`                   |
| `RadPieChart`                               | `RadPieChart`                         |

## Features

The following table maps the previous Chart features to their counterparts in the new Charts.

| Feature             | Chart (Telerik.Maui.Controls.Compatibility)     | Charts (Telerik.Maui.Controls.Charts)                                                                                                                                                                                   |
| ------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Grid lines          | `RadCartesianChart.Grid` (`CartesianChartGrid`) | `RadCartesianChart.Grid` (`CartesianChartGrid`)                                                                                                                                                                         |
| Annotations         | PlotandBand and GridLines                       | [`PlotandBand, GridLines and CategoricalPlotBandAnnotation`](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/annotations)                                                                 |
| Data point labels   | `ChartSeries.ShowLabels`                        | `ChartSeries.ShowLabels`                                                                                                                                                                                                |
| Multiple series     | Multiple series in `Series` collection          | Multiple series in `Series` collection                                                                                                                                                                                  |
| Palette             | `RadChartBase.Palette` (`ChartPalette`)         | `RadCartesianChart.Palette` (`ChartPalette`)                                                                                                                                                                            |
| Plot areas          | -                                               | [Plot Areas](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/plot-areas)                                                                                                                  |
| Stacked Bar Series  | `CombineMode` property                          | [`CombineMode`](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/series/bar-series#combine-mode) property                                                                                  |
| Null values support | Null values support                             | [Null values support](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/null-values)                                                                                                        |
| Tooltip             | Tooltip behavior                                | Tooltip for [Cartesian Charts](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/tooltip) and [Pie Charts](https://www.telerik.com/maui-ui/documentation/controls/charts/pie-chart/tooltip) |
| Trackball           | Trackball behavior                              | -                                                                                                                                                                                                                       |
| Selection           | Selection behavior                              | -                                                                                                                                                                                                                       |
| Pan and Zoom        | Pan and Zoom behavior                           | -                                                                                                                                                                                                                       |
| Legend              | Legend                                          | -                                                                                                                                                                                                                       |

## Chart Series

The core Cartesian and Pie series are available in the new Charts.

Still the new chart is in a preview state, and some series are not yet implemented. The following table lists the Chart series and their counterparts in the new Charts.

### Cartesian Series

| Chart (Telerik.Maui.Controls.Compatibility) | Charts (Telerik.Maui.Controls.Charts)                                                                                         |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `BarSeries`                                 | [`BarSeries`](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/series/bar-series)                |
| `LineSeries`                                | [`LineSeries`](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/series/line-series)              |
| `AreaSeries`                                | [`AreaSeries`](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/series/area-series)              |
| `SplineSeries`                              | [`SplineSeries`](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/series/spline-series)          |
| `SplineAreaSeries`                          | [`SplineAreaSeries`](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/series/spline-area-series) |
| `ScatterLineSeries`                         | [`Scatter Series`](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/series/scatter-series)       |
| `ScatterAreaSeries`                         | [`Scatter Series`](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/series/scatter-series)       |
| `ScatterPointSeries`                        | [`Scatter Series`](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/series/scatter-series)       |

### Pie Series

| Chart (Telerik.Maui.Controls.Compatibility) | Charts (Telerik.Maui.Controls.Charts)                                                                        |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `PieSeries`                                 | [`PieSeries`](https://www.telerik.com/maui-ui/documentation/controls/charts/pie-chart/series/pie-series)     |
| `DoughnutSeries`                            | [`DonutSeries`](https://www.telerik.com/maui-ui/documentation/controls/charts/pie-chart/series/donut-series) |

### Financial Series

| Chart (Telerik.Maui.Controls.Compatibility)             | Charts (Telerik.Maui.Controls.Charts)                                                                                                                                                                                                            |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `CandlestickSeries`, `OhlcSeries`, financial indicators | [`CandlestickSeries`](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/series/candlestick-series), [`OhlcSeries`](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/series/ohlc-series) |

The `PieSeries` data binding also changed. The previous Chart used `ValueBinding` (a `DataPointBinding`); the new `PieSeries` uses the `string`—based `ValueBinding` and `LabelBinding` properties.

## Chart Axes

The Cartesian axes keep their names and roles. Define them through the `HorizontalAxis` and `VerticalAxis` properties of the `RadCartesianChart`.

| Chart (Telerik.Maui.Controls.Compatibility) | Charts (Telerik.Maui.Controls.Charts)                                                                                    |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `CategoricalAxis`                           | [`CategoricalAxis`](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/axes/categorical-axis) |
| `NumericalAxis`                             | [`NumericalAxis`](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/axes/numerical-axis)     |
| `DateTimeContinuousAxis`                    | [`DateTimeAxis`](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/axes/datetime-axis)       |

> caption Chart (Telerik.Maui.Controls.Compatibility) axes:

```XAML
<telerik:RadCartesianChart.HorizontalAxis>
    <telerik:CategoricalAxis />
</telerik:RadCartesianChart.HorizontalAxis>
<telerik:RadCartesianChart.VerticalAxis>
    <telerik:NumericalAxis />
</telerik:RadCartesianChart.VerticalAxis>
```

> caption Charts (Telerik.Maui.Controls.Charts) axes:

```XAML
<telerik:RadCartesianChart.Axes>
    <telerik:CategoricalAxis />
    <telerik:NumericalAxis />
</telerik:RadCartesianChart.Axes>
```

## API Differences Summary

The following table summarizes the main differences between the previous and the new Charts:

| Area             | Chart (Telerik.Maui.Controls.Compatibility)            | Charts (Telerik.Maui.Controls.Charts)                                       |
| ---------------- | ------------------------------------------------------ | --------------------------------------------------------------------------- |
| Namespace        | `Telerik.Maui.Controls.Compatibility.Chart`            | `Telerik.Maui.Controls.Charts`                                              |
| XAML namespace   | `http://schemas.telerik.com/2022/xaml/maui`            | `clr-namespace:Telerik.Maui.Controls.Charts;assembly=Telerik.Maui.Controls` |
| Data binding     | `ValueBinding`, `CategoryBinding` (`DataPointBinding`) | `VerticalBinding`, `HorizontalBinding` (`string`)                           |
| Cartesian series | Bar, Line, Area, Point, Spline, Scatter                | Bar, Line, Area, Point, Spline, Scatter                                     |
| Pie series       | `PieSeries`, `DoughnutSeries`                          | `PieSeries`, `DonutSeries`                                                  |
| Financial series | OHLC, Candlestick, indicators                          | -                                                                           |
| Axes             | `Categorical`, `Numerical`, `DateTimeContinuous`       | `Categorical`, `Numerical`, `DateTime`                                      |

## See Also

* [Charts Overview](https://www.telerik.com/maui-ui/documentation/controls/charts/overview)
* [CartesianChart Overview](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/overview)
* [CartesianChart Getting Started](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/getting-started)
* [PieChart Overview](https://www.telerik.com/maui-ui/documentation/controls/charts/pie-chart/overview)
* [Bar Series](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/series/bar-series)
* [Categorical Axis](https://www.telerik.com/maui-ui/documentation/controls/charts/cartesian-chart/axes/categorical-axis)
