This guide is for those who want to upgrade from echarts 4.x (hereafter v4
) to echarts 5.x (hereafter v5
). You can find out what new features v5
brings that are worth upgrading in New Features in ECharts 5. In most cases, developers won‘t need to do anything extra for this upgrade, as echarts has always tried to keep the API as stable and backward-compatible as possible. However, v5
still brings some breaking changes that require special attention. In addition, in some cases, v5
provides a better API to replace the previous one, and these superseded APIs will no longer be recommended (though we have tried to be as compatible as possible with these changes). We’ll try to explain these changes in detail in this document.
First of all, the default theme has been changed. v5
has made a lot of changes and optimizations on the theme design. If you still want to keep the colors of the old version, you can manually declare the colors as follows.
chart.setOption({ color: [ '#c23531', '#2f4554', '#61a0a8', '#d48265', '#91c7ae', '#749f83', '#ca8622', '#bda29a', '#6e7074', '#546570', '#c4ccd3' ] // ... });
Or, to make a simple v4
theme.
var themeEC4 = { color: [ '#c23531', '#2f4554', '#61a0a8', '#d48265', '#91c7ae', '#749f83', '#ca8622', '#bda29a', '#6e7074', '#546570', '#c4ccd3' ] }; var chart = echarts.init(dom, themeEC4); chart.setOption(/* ... */);
Since v5
, echarts only provides named exports
.
So if you are importing echarts
like this:
import echarts from 'echarts'; // Or import core module import echarts from 'echarts/lib/echarts';
It will throw error in v5
. You need to change the code as follows to import the entire module.
import * as echarts from 'echarts'; // Or import * as echarts from 'echarts/lib/echarts';
In 5.0.1, we introduced the new tree-shaking API
import * as echarts from 'echarts/core'; import { BarChart } from 'echarts/charts'; import { GridComponent } from 'echarts/components'; // Note that the Canvas renderer is no longer included by default and needs to be imported explictly, or import the SVGRenderer if you need to use the SVG rendering mode import { CanvasRenderer } from 'echarts/renderers'; echarts.use([BarChart, GridComponent, CanvasRenderer]);
To make it easier for you to know which modules you need to import based on your option, our new example page adds a new feature to generate the three-shakable code, you can check the Full Code
tab on the example page to see the modules you need to introduce and the related code.
In most cases, we recommend using the new tree-shaking interface whenever possible, as it maximizes the power of the packaging tool tree-shaking and effectively resolves namespace conflicts and prevents the exposure of internal structures. If you are still using the CommonJS method of writing modules, the previous approach is still supported:
const echarts = require('echarts/lib/echarts'); require('echarts/lib/chart/bar'); require('echarts/lib/component/grid');
Second, because our source code has been rewritten using TypeScript, v5
will no longer support importing files from echarts/src
. You need to change it to import from echarts/lib
.
Note: This section is only for developers who use tree-shaking interfaces to ensure a minimal bundle size, not for those who imports the whole package.
In order to keep the size of the bundle small enough, we remove some dependencies that would have been imported by default. For example, as mentioned above, when using the new on-demand interface, CanvasRenderer
is no longer introduced by default, which ensures that unneeded Canvas rendering code is not imported when only SVG rendering mode is used, and in addition, the following dependencies are adjusted.
const echarts = require('echarts/lib/echarts'); require('echarts/lib/chart/bar'); require('echarts/lib/chart/line');
Need to introduce the grid
component separately again
require('echarts/lib/component/grid');
Reference issues: #14080, #13764
aria
components are no longer imported by default. You need import it manually if necessary.import { AriaComponent } from 'echarts/components'; echarts.use(AriaComponent);
Or
require('echarts/lib/component/aria');
v5
removes the built-in geoJSON (previously in the echarts/map
folder). These geoJSON files were always sourced from third parties. If users still need them, they can go get them from the old version, or find more appropriate data and register it with ECharts via the registerMap interface.
IE8 is no longer supported by v5
. We no longer maintain and upgrade the previous VML renderer for IE8 compatibility. If developers have a strong need for a VML renderer, they are welcome to submit a pull request to upgrade the VML renderer or maintain a separate third-party VML renderer, as we support registration of standalone renderers starting with v5.0.1
.
The priority of the visuals between visualMap component and itemStyle | lineStyle | areaStyle are reversed since v5
.
That is, previously in v4
, the visuals (i.e., color, symbol, symbolSize, ...) that generated by visualMap component has the highest priority, which will overwrite the same visuals settings in itemStyle | lineStyle | areaStyle. That brought troubles when needing to specify specific style to some certain data items while using visualMap component. Since v5
, the visuals specified in itemStyle | lineStyle | areaStyle has the highest priority.
In most cases, users will probably not notice this change when migrating from v4
to v5
. But users can still check that if visualMap component and itemStyle | lineStyle | areaStyle are both specified.
padding
for Rich Textv5
adjusts the rich.?.padding to make it more compliant with CSS specifications. In v4
, for example rich. .padding: [11, 22, 33, 44]
means that padding-top
is 33
and padding-bottom
is 11
. The position of the top and bottom is adjusted in v5
, rich. .padding: [11, 22, 33, 44]
means that padding-top
is 11
and padding-bottom
is 33
.
If the user is using rich.?.padding, this order needs to be adjusted.
These extensions need to be upgraded to new version to support echarts v5
:
Some of the API and echarts options are deprecated since v5
, but are still backward compatible. Users can keep using these deprecated API, with only some warning will be printed to console in dev mode. But if users have spare time, it is recommended to upgraded to new API for the consideration of long term maintenance.
The deprecated API and their corresponding new API are listed as follows:
position: [number, number]
are changed to x: number
/y: number
.scale: [number, number]
are changed to scaleX: number
/scaleY: number
.origin: [number, number]
are changed to originX: number
/originY: number
.position
, scale
and origin
are still supported but deprecated.graphic
components: the declarations of each element.custom series
: the declarations of each element in the return of renderItem
.style.text
are deprecated in elements except Text
. Instead, Prop set textContent
and textConfig
are provided to support more powerful capabilities.style
and style.rich.?
. Use the props at the right part below instead.graphic
components: the declarations of each element. [compat, but not accurately the same in some complicated cases.]custom series
: the declarations of each element in the return of renderItem
. [compat, but not accurately the same in some complicated cases].chart.one(...)
is deprecated.label
:color
, textBorderColor
, backgroundColor
and borderColor
, the value 'auto'
is deprecated. Use the value 'inherit'
instead.hoverAnimation
:series.hoverAnimation
is deprecated. Use series.emphasis.scale
instead.line series
:series.clipOverflow
is deprecated. Use series.clip
instead.custom series
:renderItem
, the api.style(...)
and api.styleEmphasis(...)
are deprecated. Because it is not really necessary and hard to ensure backward compatibility. Users can fetch system designated visual by api.visual(...)
.sunburst series
:highlight
is deprecated. Use sunburstHighlight
instead.downplay
is deprecated. Use sunburstUnhighlight
instead.series.downplay
is deprecated. Use series.blur
instead.series.highlightPolicy
is deprecated. Use series.emphasis.focus
instead.pie series
:pieToggleSelect
=> toggleSelect
pieSelect
=> select
pieUnSelect
=> unselect
pieselectchanged
=> selectchanged
pieselected
=> selected
pieunselected
=> unselected
series.label.margin
is deprecated. Use series.label.edgeDistance
instead.series.clockWise
is deprecated. Use series.clockwise
instead.series.hoverOffset
is deprecated. Use series.emphasis.scaleSize
instead.map series
:mapToggleSelect
=> toggleSelect
mapSelect
=> select
mapUnSelect
=> unselect
mapselectchanged
=> selectchanged
mapselected
=> selected
mapunselected
=> unselected
series.mapType
is deprecated. Use series.map
instead.series.mapLocation
is deprecated.graph series
:series.focusNodeAdjacency
is deprecated. Use series.emphasis: { focus: 'adjacency'}
instead.gauge series
:series.clockWise
is deprecated. Use series.clockwise
instead.series.hoverOffset
is deprecated. Use series.emphasis.scaleSize
instead.dataZoom component
:dataZoom.handleIcon
need prefix path://
if using SVGPath.radar
:radar.name
is deprecated. Use radar.axisName
instead.radar.nameGap
is deprecated. Use radar.axisNameGap
instead.echarts.format.formatTime
is deprecated. Use echarts.time.format
instead.echarts.number.parseDate
is deprecated. Use echarts.time.parse
instead.echarts.format.getTextRect
is deprecated.