Migrating from v1 to v2

Version 2 replaces deprecated axis padding, tick spacing, numeric unit and bar label options. You can update these settings directly or use the migration adapter to convert existing configurations.

The main replacements are:

Update dependenciesUpdate dependencies

Install @gravity-ui/charts@^2 together with @gravity-ui/uikit@^8. React and React DOM 18 or later are required. Follow the UIKit migration guide when upgrading UIKit.

The package provides ESM and CommonJS builds through its public entry points. Import from @gravity-ui/charts or a documented subpath; replace imports that reach into dist or other internal directories.

Render an existing configurationRender an existing configuration

Import the migration adapter from @gravity-ui/charts/migration/v1 and pass its result to the chart:

import {Chart} from '@gravity-ui/charts';
import {migrateChartDataV1} from '@gravity-ui/charts/migration/v1';
import type {ChartDataV1} from '@gravity-ui/charts/migration/v1';

const legacyData: ChartDataV1 = {
  yAxis: [
    {
      ticks: {pixelInterval: 60},
      labels: {numberFormat: {unit: 'k'}},
    },
  ],
  series: {
    data: [
      {
        type: 'line',
        name: 'Revenue',
        data: [
          {x: 1, y: 1500},
          {x: 2, y: 2000},
        ],
      },
    ],
  },
};

const {data, warnings} = migrateChartDataV1(legacyData);

<Chart data={data} />;

Run migration when the configuration changes. In React, memoize the result by the input configuration. The adapter does not mutate the input, execute callbacks or print warnings to the console. Unchanged objects retain their references.

The /migration/v1 entry point also works in Node.js without loading React or chart plugins. ChartDataV1 accepts the removed aliases; use ChartData for configurations that already use the v2 options.

Replace removed optionsReplace removed options

Tick spacingTick spacing

Replace ticks.pixelInterval: 120 with ticks.interval: 120. Numeric intervals are pixels. The adapter preserves v1's precedence when both fields are present: a truthy interval wins; otherwise pixelInterval is used.

Numeric unitsNumeric units

Replace unit with units. Use a fixed scale and an empty delimiter to retain v1's compact suffix:

// Before
{type: 'number', unit: 'k'}

// After: every value is expressed in thousands, including values below 1000.
{
  type: 'number',
  units: {
    scale: [{factor: 1000, postfix: 'K'}],
    delimiter: '',
  },
}

For the other legacy values:

• unit: 'auto': set units to {...FORMAT_UNITS_NUMBERS, delimiter: ''}, importing the preset from @gravity-ui/charts.
• unit: 'm', 'b' or 't': use a fixed scale with factor 1e6, 1e9 or 1e12 and suffix M, B or T.
• unit: null: use a fixed scale with factor 1, an empty postfix and an empty delimiter. On numeric axes, this also disables automatic abbreviation.

An existing units scale keeps its priority. An omitted or undefined scale keeps automatic axis abbreviation.

Bar label placementBar label placement

For Bar-X and Bar-Y, replace dataLabels.inside: true with placement: ['inside-center']. Remove inside: false to retain the default outside placement without changing the space reserved for labels.

Percent stacks use inside labels by default; remove inside regardless of its value. The adapter preserves explicit placement settings. Funnel's inside setting remains supported.

Migrate axis paddingMigrate axis padding

maxPadding has been removed. Replace maxPadding: 0.25 with padding: {max: '25%'}. Percentages extend the original axis domain before other padding and tick rounding.

The adapter converts this field automatically, preserves padding.min and keeps any explicit padding.max, including 0 and 'auto'. See axis padding for the replacement options and their interaction with explicit limits.

Review migration warningsReview migration warnings

Both migration functions return structured diagnostics for the original input. To inspect a configuration without changing it, call inspectChartDataV1:

import {inspectChartDataV1} from '@gravity-ui/charts/migration/v1';

const warnings = inspectChartDataV1(savedConfiguration);

Each diagnostic contains:

• code: an identifier your application can map to localized text.
• path: property names and array indices locating the option in the input.
• message: an English description.
• resolution: automatic for applied conversions, or review for cases that need attention.
• replacement: a suggested replacement, when known.

For example, a removed tick option produces axis-pixel-interval at ['yAxis', 0, 'ticks', 'pixelInterval']. Axis padding, numeric unit and bar label conversions produce axis-max-padding, number-unit and bar-label-inside. Invalid legacy values remain unchanged and produce invalid-axis-max-padding, invalid-axis-pixel-interval, invalid-number-unit or invalid-bar-label-inside with resolution: 'review'.

Bar-X and Scatter point category remains supported but deprecated; the adapter reports point-category once per series at the first matching point and preserves raw point fields. Click handlers also remain supported with the same default mode and callback arguments. tooltip.rowRenderer remains supported and needs no migration.

Diagnostics are returned only when you call the adapter or inspector. Custom payloads and callback bodies are not scanned. If a callback constructs an old formatting configuration, update that code directly.