The echarts.init() method creates and initializes an ECharts instance on a specified DOM element.
Signature
function init(
dom?: HTMLElement | null,
theme?: string | object | null,
opts?: EChartsInitOpts
): EChartsType
Parameters
dom
HTMLElement | null
default:"null"
The DOM element to mount the chart. Must have width and height (except for canvas elements or when width/height specified in opts).const dom = document.getElementById('main');
const chart = echarts.init(dom);
In SSR mode (opts.ssr = true), the dom parameter can be null.
theme
string | ThemeOption | null
default:"null"
Theme to apply. Can be:
- A registered theme name (string)
- A theme object
null for default theme
// Using registered theme
echarts.registerTheme('vintage', { /* theme options */ });
const chart = echarts.init(dom, 'vintage');
// Using theme object directly
const chart = echarts.init(dom, {
color: ['#c23531', '#2f4554', '#61a0a8'],
backgroundColor: '#f4f4f4'
});
EChartsInitOpts Properties
opts.renderer
'canvas' | 'svg'
default:"'canvas'"
Renderer type. Canvas is more performant, SVG provides better scalability and smaller file size for simple charts.const chart = echarts.init(dom, null, { renderer: 'svg' });
opts.devicePixelRatio
number
default:"window.devicePixelRatio"
Device pixel ratio for high-DPI displays. Defaults to window.devicePixelRatio.const chart = echarts.init(dom, null, { devicePixelRatio: 2 });
opts.width
number | string
default:"dom.clientWidth"
Explicit width in pixels. Can be a number or ‘auto’. By default uses the DOM element’s clientWidth.const chart = echarts.init(dom, null, { width: 800 });
opts.height
number | string
default:"dom.clientHeight"
Explicit height in pixels. Can be a number or ‘auto’. By default uses the DOM element’s clientHeight.const chart = echarts.init(dom, null, { height: 600 });
opts.locale
string | LocaleOption
default:"'ZH'"
Locale for internationalization. Can be a locale name string or a complete locale object.// Use built-in locale
const chart = echarts.init(dom, null, { locale: 'EN' });
// Custom locale object
const chart = echarts.init(dom, null, {
locale: {
time: {
month: ['Jan', 'Feb', 'Mar', ...],
monthAbbr: ['Jan', 'Feb', 'Mar', ...]
}
}
});
Enable dirty rectangle optimization for better rendering performance. Only redraws changed areas.const chart = echarts.init(dom, null, { useDirtyRect: true });
This is an experimental feature. Use with caution in production.
opts.useCoarsePointer
boolean | 'auto'
default:"'auto'"
Whether to use coarse pointer (larger hit test areas for touch devices).
true: Always use coarse pointerfalse: Never use coarse pointer'auto': Auto-detect based on device
const chart = echarts.init(dom, null, { useCoarsePointer: true });
Pointer size for hit testing when using coarse pointer mode.const chart = echarts.init(dom, null, {
useCoarsePointer: true,
pointerSize: 20
});
Enable server-side rendering mode. When true, the chart can be rendered without a DOM element.const chart = echarts.init(null, null, { ssr: true });
Returns
An ECharts instance with methods for configuration, interaction, and lifecycle management.See ECharts Instance for available methods. Examples
Basic Initialization
import * as echarts from 'echarts';
const dom = document.getElementById('main');
const chart = echarts.init(dom);
chart.setOption({
title: { text: 'Sales Data' },
xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
yAxis: { type: 'value' },
series: [{ type: 'line', data: [120, 200, 150] }]
});
Using SVG Renderer
const chart = echarts.init(dom, null, {
renderer: 'svg',
width: 800,
height: 600
});
chart.setOption({
// ... chart options
});
// Export as SVG string
const svgStr = chart.renderToSVGString();
With Theme and High DPI
// Register custom theme
echarts.registerTheme('my-theme', {
color: ['#3398DB', '#EE6666', '#73C0DE'],
backgroundColor: '#f4f4f4',
textStyle: {
color: '#333'
}
});
// Initialize with theme and retina display support
const chart = echarts.init(dom, 'my-theme', {
devicePixelRatio: window.devicePixelRatio || 2
});
Server-Side Rendering
import * as echarts from 'echarts';
import { createCanvas } from 'canvas'; // Node.js canvas library
// Initialize without DOM in SSR mode
const chart = echarts.init(null, null, {
renderer: 'svg',
ssr: true,
width: 800,
height: 600
});
chart.setOption({
// ... chart options
});
// Get SVG string for server-side rendering
const svgString = chart.renderToSVGString();
Responsive Chart with Dirty Rect Optimization
const chart = echarts.init(dom, null, {
useDirtyRect: true,
useCoarsePointer: 'auto'
});
chart.setOption({ /* ... */ });
// Handle window resize
window.addEventListener('resize', () => {
chart.resize();
});
Important Behaviors
Existing Instance Detection: If an ECharts instance already exists on the provided DOM element, init() will return the existing instance instead of creating a new one. Always dispose of old instances before creating new ones if needed.// Dispose existing instance first
const existing = echarts.getInstanceByDom(dom);
if (existing) {
existing.dispose();
}
const chart = echarts.init(dom);
DOM Requirements: The DOM element should have explicit width and height set via CSS or inline styles. Zero-width or zero-height elements will trigger a warning.#main {
width: 800px;
height: 600px;
}
Canvas Elements: When using a <canvas> element as the DOM, width and height requirements are more flexible as they can be specified in the opts parameter.
Canvas vs SVG
- Canvas: Better for charts with large amounts of data points or frequent updates
- SVG: Better for charts with fewer elements, or when you need to manipulate individual elements via DOM
Dirty Rectangle Rendering
Enable useDirtyRect for better performance with frequent updates:
const chart = echarts.init(dom, null, { useDirtyRect: true });
// Only changed areas will be redrawn
setInterval(() => {
chart.setOption({
series: [{ data: generateNewData() }]
});
}, 1000);
See Also