Normal Merge mode behavior
In Normal Merge mode, each component description in incoming option is mapped and merged into existing components by matching id or name first, then by position order, with remaining components created at the tail. No existing components are removed, component indices never change, and if no id/name is specified, components merge intuitively by position.
Replace Merge mode behavior
In Replace Merge mode, only existing components with matching ids from incoming option are kept. Other existing components are removed (set to null in list to preserve indices). Remaining unmatched component descriptions from option create new components at freed positions or tail. This enables partial component removal while preserving indices of unremoved components.
Component removal strategies
Total removal: use notMerge: true to remove all components. Partial removal: use replaceMerge: [...] to remove only specified component types if their ids don't match incoming option. Partial removal is useful to preserve state (highlight, animation, selected area) of other components while removing specific types.
Option object purpose and structure
The option object is a JavaScript object that defines all requirements for an echarts instance: data, visual mapping, and interaction. It contains properties for each component type, with single components as objects and multiple components of the same type as arrays. Each component can specify a type to indicate its sub-type.
setOption for asynchronous data loading
After initializing a chart with echarts.init(), you can call setOption at any time to pass in data and configuration items retrieved through asynchronous operations like jQuery $.get(). This allows data to be filled in after being fetched from external sources rather than only at initialization.
Two-phase loading pattern: display empty chart then fill data
You can initialize a chart with empty data arrays and then call setOption again later to fill in the actual data once it is loaded asynchronously. First call setOption with empty arrays for xAxis.data and series[].data to display the empty chart structure, then call setOption again with the loaded data to update the chart.
Series matching by name for data updates
When updating data through setOption, ECharts finds the corresponding series using the series name property. It is recommended to always define series name information for reliable data updates. If name is not defined, updating may work by series order in some cases, but using name is the safer approach.
Dynamic data updates drive chart presentation changes
In ECharts, all data updates are performed through setOption. When data changes, ECharts automatically finds the difference between the old and new data and presents the changes through appropriate animations. You do not need to manually manage transitions or specify what changed; simply call setOption with new data.
addData method removed in ECharts 3
The addData method that existed in ECharts 2 has been removed in ECharts 3. To add a single data point, use data.push(value) to modify the data array, then call setOption with the updated array.
Example: asynchronous data loading with setOption
var myChart = echarts.init(document.getElementById('main'));
$.get('data.json').done(function (data) {
myChart.setOption({
title: {
text: 'asynchronous data loading example'
},
tooltip: {},
legend: {
data:['Sales']
},
xAxis: {
data: data.categories
},
yAxis: {},
series: [{
name: 'Sales',
type: 'bar',
data: data.data
}]
});
});
This example shows loading external data via jQuery and passing it to setOption after the chart is initialized.
Example: two-phase loading with empty chart
var myChart = echarts.init(document.getElementById('main'));
// show title. legend and empty axis
myChart.setOption({
title: {
text: 'asynchronous data loading example'
},
tooltip: {},
legend: {
data:['Sales']
},
xAxis: {
data: []
},
yAxis: {},
series: [{
name: 'Sales',
type: 'bar',
data: []
}]
});
// Asynchronous data loading
$.get('data.json').done(function (data) {
// fill in data
myChart.setOption({
xAxis: {
data: data.categories
},
series: [{
// find series by name
name: 'Sales',
data: data.data
}]
});
});
This example shows initializing a chart with empty data structures, then filling in actual data after it loads asynchronously.