Migration from v8 to v9

This guide describes the changes needed to migrate Charts from v8 to v9.

Introduction

This is a reference guide for upgrading @mui/x-charts from v8 to v9.

Start using the new release

In package.json, change the version of the charts package to latest.

-"@mui/x-charts": "^8.x.x",
+"@mui/x-charts": "latest",

-"@mui/x-charts-pro": "^8.x.x",
+"@mui/x-charts-pro": "latest",

Since v9 is a major release, it contains changes that affect the public API. These changes were done for consistency, improved stability and to make room for new features. Described below are the steps needed to migrate from v8 to v9.

Run codemods

The preset-safe codemod will automatically adjust the bulk of your code to account for breaking changes in v9. You can run v9.0.0/charts/preset-safe targeting only Charts or v9.0.0/preset-safe to target the other packages as well.

You can either run it on a specific file, folder, or your entire codebase when choosing the <path> argument.

# Charts-specific
npx @mui/x-codemod@next v9.0.0/charts/preset-safe <path>

# Target the other packages as well
npx @mui/x-codemod@next v9.0.0/preset-safe <path>

Breaking changes that are handled by this codemod are denoted by a ✅ emoji in the table of contents on the right side of the screen.

If you have already applied the v9.0.0/charts/preset-safe (or v9.0.0/preset-safe) codemod, then you should not need to take any further action on these items.

All other changes must be handled manually.

Not all use cases are covered by codemods. In some scenarios, like props spreading or cross-file dependencies, the changes are not properly identified and therefore must be handled manually.

For example, if a codemod tries to rename a prop, but this prop is hidden with the spread operator, it won't be transformed as expected.

<PieChart {...chartProps} /> // The codemod will not modify the content of `chartProps`.

After running the codemods, make sure to test your application and that you don't have any console errors.

Feel free to open an issue for support if you need help to proceed with your migration.

Change `seriesId` type to `string`

The seriesId property accepted number | string. In v9, only string is accepted.

This type modification impacts the objects in the series props, as well as the highlightedItem and tooltipItem objects.

Removed deprecated types and APIs

The following deprecated types, interfaces, and APIs that were marked as deprecated in v8 have been removed in v9.

Series types

The following type aliases have been removed from @mui/x-charts/models:

CartesianSeriesType - Use AllSeriesType<CartesianChartSeriesType> directly if needed
DefaultizedCartesianSeriesType - Use DefaultizedSeriesType<CartesianChartSeriesType> directly if needed
StackableSeriesType - Use DefaultizedSeriesType<StackableChartSeriesType> directly if needed

-import { CartesianSeriesType } from '@mui/x-charts/models';
+import { AllSeriesType } from '@mui/x-charts/models';
+import type { CartesianChartSeriesType } from '@mui/x-charts/internals';
+
+type CartesianSeriesType = AllSeriesType<CartesianChartSeriesType>;

✅ `ChartApi` type moved to `@mui/x-charts/context`

The ChartApi type export has been moved from @mui/x-charts/ChartContainer to @mui/x-charts/context.

-import type { ChartApi } from '@mui/x-charts/ChartContainer';
+import type { ChartApi } from '@mui/x-charts/context';

Series helper functions

The following helper functions have been removed:

isDefaultizedBarSeries() - Check series.type === 'bar' directly
isBarSeries() - Check series.type === 'bar' directly

-import { isBarSeries } from '@mui/x-charts/models';
-
-if (isBarSeries(series)) {
+if (series.type === 'bar') {
   // Handle bar series
 }

Hooks

`use[Type]Series()` with empty array

When use[Type]Series() hooks received an empty array, they returned all the available series of the given type. In v9 they return an empty array.

// In v8
useBarSeries(['id-1']); // Returns [{ id: "id-1", ... }]
useBarSeries([]); // Returns [{ id: "id-1", ... }, { id: "id-2", ... }, ...]

// In v9
useBarSeries(['id-1']); // Returns [{ id: "id-1", ... }]
useBarSeries([]); // Returns []

Rename `useAxisTooltip` hook

The useAxisTooltip hook has been renamed to useAxesTooltip to better reflect its functionality of handling multiple axes.

The hook now always returns an array of tooltip data (one entry per active axis) instead of a single object.

-import { useAxisTooltip, UseAxisTooltipReturnValue, UseAxisTooltipParams } from '@mui/x-charts';
+import { useAxesTooltip, UseAxesTooltipReturnValue, UseAxesTooltipParams } from '@mui/x-charts';

Run the following command to do the renaming.

npx @mui/x-codemod@next v9.0.0/charts/rename-axis-tooltip-hook <path|folder>

After running the codemod make sure to adapt the hook returned value to your needs.

 function CustomTooltip() {
   // If you want to keep only one axis
-  const tooltipData = useAxisTooltip();
+  const tooltipData = useAxesTooltip()[0] ?? null;
   // If you use all the axes
-  const tooltipData = useAxisTooltip({ multipleAxes: true });
+  const tooltipData = useAxesTooltip();
 }

Heatmap

`hideLegend` default value changed ✅

The default value of the hideLegend prop in the Heatmap component has changed from true to false in v9. This improves consistency across chart components and developer experience.

 <Heatmap
+  hideLegend
 />

-import { axisClasses } from '@mui/x-charts/ChartsAxis';
-
-// CSS selector
-`.MuiChartsAxis-id-myXAxis`
-// Or using axisClasses
-`.${axisClasses.id}-myXAxis`
+import { axisClasses } from '@mui/x-charts/ChartsAxis';
+
+// CSS selector
+`.MuiChartsAxis-root[data-axis-id="myXAxis"]`
+// Or using axisClasses
+`.${axisClasses.root}[data-axis-id="myXAxis"]`

If you're using the sx prop or styled():

 <LineChart
   sx={{
-    [`& .MuiChartsAxis-id-myXAxis`]: {
+    [`& .MuiChartsAxis-root[data-axis-id="myXAxis"]`]: {
       // Your custom styles
     },
   }}
 />