ngx-echarts is an Angular (ver >= 2.x) directive for ECharts (ver >= 3.x).
Latest version @npm:
-
v20.0.1for Angular 20 -
v19.0.0for Angular 19 -
v18.0.0for Angular 18 -
v17.2.0for Angular 17 -
v16.2.0for Angular 16 -
v15.0.3for Angular 15 -
v14.0.0for Angular 14 -
v8.0.1for Angular 13 -
v7.1.0for Angular >= 11, < 13 -
v6.0.1for Angular >= 10, < 11 -
v5.2.2for Angular >= 6, < 10 -
v2.3.1for Angular < 6 (Please refer to https://github.com/xieziyu/ngx-echarts/blob/v2.x/README.md)
A starter project on Github: https://github.com/xieziyu/ngx-echarts-starter
-
2025.06.26: v20.0.1
- fix:
[theme]input issue #28
- fix:
-
2025.06.09: v20.0.0
- feat: Upgrade to angular 20
- feat: Zoneless compatibility
- refactor: Migrate the project to modern angular patterns. (Thanks to pkurcx)
-
Since v5.0
# if you use npm npm install echarts -S npm install ngx-echarts -S # or if you use yarn yarn add echarts yarn add ngx-echarts
-
If you need ECharts GL support, please install it first:
npm install echarts-gl -S # or yarn add echarts-gl -
Import other extensions such as themes or
echarts-glin yourmain.ts: ECharts Extensions
- import
echartsand provide it inNgxEchartsModule.forRoot({ echarts }). -
NgxEchartsCoreModuleis removed.
Please refer to the demo page.
import NgxEchartsDirective and provideEchartsCore. Or you can use provideEchartsCore to do treeshaking custom build.
import { NgxEchartsDirective, provideEchartsCore } from 'ngx-echarts'; // import echarts core import * as echarts from 'echarts/core'; // import necessary echarts components import { BarChart } from 'echarts/charts'; import { GridComponent } from 'echarts/components'; import { CanvasRenderer } from 'echarts/renderers'; echarts.use([BarChart, GridComponent, CanvasRenderer]); @Component({ selector: 'app-root', standalone: true, imports: [CommonModule, NgxEchartsDirective], templateUrl: './app.component.html', styleUrls: ['./app.component.scss'], providers: [provideEchartsCore({ echarts })], }) export class AppComponent {}import NgxEchartsModule:
import { NgxEchartsModule } from 'ngx-echarts'; // import echarts core import * as echarts from 'echarts/core'; // import necessary echarts components import { BarChart } from 'echarts/charts'; import { GridComponent } from 'echarts/components'; import { CanvasRenderer } from 'echarts/renderers'; echarts.use([BarChart, GridComponent, CanvasRenderer]); @NgModule({ imports: [NgxEchartsModule.forRoot({ echarts })], }) export class AppModule {}use echarts directive in a div which has pre-defined height. (From v2.0, it has default height: 400px)
- html:
<div echarts [options]="chartOption" class="demo-chart"></div>- css:
.demo-chart { height: 400px; }- component:
import { EChartsCoreOption } from 'echarts/core'; // ... chartOption: EChartsCoreOption = { xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'], }, yAxis: { type: 'value', }, series: [ { data: [820, 932, 901, 934, 1290, 1330, 1320], type: 'line', }, ], };echarts directive support following input properties:
| Input | Type | Default | Description |
|---|---|---|---|
[options] | object | null | The same as the options on the official demo site. |
[merge] | object | null | Used to update a part of the options, especially helpful when you need to update the chart data. In fact, the value of merge will be used in echartsInstance.setOption() with notMerge = false. Refer to ECharts documentation for details. |
[loading] | boolean | false | Used to toggle the echarts loading animation when your data is not ready. |
[autoResize] | boolean | true | If set to true, the chart will be automatically resized when the window's width is changed. |
[initOpts] | object | null | The value of [initOpts] will be used in echarts.init(). It may contain devicePixelRatio, renderer, width or height properties. Refer to ECharts documentation for details. |
[theme] | string | null | Used it to initialize echarts with theme. The theme file must also be imported in main.ts. |
[loadingOpts] | object | null | Input an object to customize the loading style. Refer to ECharts documentation for details. |
By default, loadingOpts is:
{ text: 'loading', color: '#c23531', textColor: '#000', maskColor: 'rgba(255, 255, 255, 0.8)', zlevel: 0 }If you need to access parts of the ECharts API such as echarts.graphic, please import it from echarts. For example:
import { graphic } from 'echarts/core'; new graphic.LinearGradient(/* ... */);echartsInstance is exposed (since v1.1.6) in the (chartInit) event, enabling you to directly call functions like: resize(), showLoading(), etc. For example:
- html:
<div echarts class="demo-chart" [options]="chartOptions" (chartInit)="onChartInit($event)"></div>- component:
onChartInit(ec) { this.echartsInstance = ec; } resizeChart() { if (this.echartsInstance) { this.echartsInstance.resize(); } }Import echarts theme files or other extension files after you have imported echarts core. For example:
import * as echarts from 'echarts/core'; /** echarts extensions: */ import { Bar3DChart } from 'echarts-gl/charts'; import { Grid3DComponent } from 'echarts-gl/components'; import 'echarts/theme/macarons.js'; import 'echarts/dist/extension/bmap.min.js';NgxEchartsService has been obsolete since v4.0
As ECharts supports the 'click', 'dblclick', 'mousedown', 'mouseup', 'mouseover', 'mouseout', and 'globalout' mouse events, our ngx-echarts directive also supports the same mouse events but with an additional chart prefix. For example:
- html:
<div echarts class="demo-chart" [options]="chartOptions" (chartClick)="onChartClick($event)"></div>- The '$event' is same with the 'params' that ECharts dispatches.
It supports following event outputs:
| @Output | Event |
|---|---|
| chartInit | Emitted when the chart is initialized |
| chartClick | echarts event: 'click' |
| chartDblClick | echarts event: 'dblclick' |
| chartMouseDown | echarts event: 'mousedown' |
| chartMouseMove | echarts event: 'mousemove' |
| chartMouseUp | echarts event: 'mouseup' |
| chartMouseOver | echarts event: 'mouseover' |
| chartMouseOut | echarts event: 'mouseout' |
| chartGlobalOut | echarts event: 'globalout' |
| chartContextMenu | echarts event: 'contextmenu' |
| chartHighlight | echarts event: 'highlight' |
| chartDownplay | echarts event: 'downplay' |
| chartSelectChanged | echarts event: 'selectchanged' |
| chartLegendSelectChanged | echarts event: 'legendselectchanged' |
| chartLegendSelected | echarts event: 'legendselected' |
| chartLegendUnselected | echarts event: 'legendunselected' |
| chartLegendLegendSelectAll | echarts event: 'legendselectall' |
| chartLegendLegendInverseSelect | echarts event: 'legendinverseselect' |
| chartLegendScroll | echarts event: 'legendscroll' |
| chartDataZoom | echarts event: 'datazoom' |
| chartDataRangeSelected | echarts event: 'datarangeselected' |
| chartGraphRoam | echarts event: 'graphroam' |
| chartGeoRoam | echarts event: 'georoam' |
| chartTreeRoam | echarts event: 'treeroam' |
| chartTimelineChanged | echarts event: 'timelinechanged' |
| chartTimelinePlayChanged | echarts event: 'timelineplaychanged' |
| chartRestore | echarts event: 'restore' |
| chartDataViewChanged | echarts event: 'dataviewchanged' |
| chartMagicTypeChanged | echarts event: 'magictypechanged' |
| chartGeoSelectChanged | echarts event: 'geoselectchanged' |
| chartGeoSelected | echarts event: 'geoselected' |
| chartGeoUnselected | echarts event: 'geounselected' |
| chartAxisAreaSelected | echarts event: 'axisareaselected' |
| chartBrush | echarts event: 'brush' |
| chartBrushEnd | echarts event: 'brushend' |
| chartBrushSelected | echarts event: 'brushselected' |
| chartGlobalCursorTaken | echarts event: 'globalcursortaken' |
| chartRendered | echarts event: 'rendered' |
| chartFinished | echarts event: 'finished' |
You can refer to the ECharts tutorial: Events and Actions in ECharts for more details of the event params. You can also refer to the demo page for a detailed example.
Since version 5.0.1 ECharts supports Treeshaking with NPM.
The app.modules.ts should look like this:
import { BrowserModule } from '@angular/platform-browser'; import { NgModule } from '@angular/core'; import { HttpClientModule } from '@angular/common/http'; import { NgxEchartsDirective, provideEchartsCore } from 'ngx-echarts'; import { AppComponent } from './app.component'; // Import the echarts core module, which provides the necessary interfaces for using echarts. import * as echarts from 'echarts/core'; // Import bar charts, all suffixed with Chart import { BarChart } from 'echarts/charts'; // Import the tooltip, title, rectangular coordinate system, dataset and transform components import { TitleComponent, TooltipComponent, GridComponent, DatasetComponent, TransformComponent } from 'echarts/components'; // Features like Universal Transition and Label Layout import { LabelLayout, UniversalTransition } from 'echarts/features'; // Import the Canvas renderer // Note that including the CanvasRenderer or SVGRenderer is a required step import { CanvasRenderer } from 'echarts/renderers'; // Import the theme import 'echarts/theme/macarons.js'; // Register the required components echarts.use([ BarChart, TitleComponent, TooltipComponent, GridComponent, DatasetComponent, TransformComponent, LabelLayout, UniversalTransition, CanvasRenderer ]); @NgModule({ declarations: [AppComponent], imports: [ BrowserModule, HttpClientModule, // import standalone directive: NgxEchartsDirective, ], providers: [{ // Provide custom builded ECharts core: provideEchartsCore({ echarts }) }], bootstrap: [AppComponent], }) export class AppModule {}Please refer to ECharts Documentation for more details.
If you want to produce a custom build of ECharts, prepare a file like custom-echarts.ts:
// custom-echarts.ts export * from 'echarts/src/echarts'; import 'echarts/src/chart/line'; import 'echarts/src/chart/bar'; // component examples: import 'echarts/src/component/tooltip'; import 'echarts/src/component/title'; import 'echarts/src/component/toolbox';And then inject it in your NgxEchartsModule:
import { NgxEchartsModule } from 'ngx-echarts'; import * as echarts from './custom-echarts'; @NgModule({ imports: [ NgxEchartsModule.forRoot({ echarts, }), ], }) export class AppModule {}And if you want to use the global echarts object, please import it from lib or src instead:
import * as echarts from 'echarts/lib/echarts';If you need to import theme files, remember to change the 'echarts' path to 'echarts/lib/echarts', for example:
// ... part of echarts/theme/dark.js: function (root, factory) { if (typeof define === 'function' && define.amd) { // AMD. Register as an anonymous module. define(['exports', 'echarts/lib/echarts'], factory); } else if (typeof exports === 'object' && typeof exports.nodeName !== 'string') { // CommonJS factory(exports, require('echarts/lib/echarts')); } else { // Browser globals factory({}, root.echarts); } }You can change the chart locale registering a built-in locale (located in node_modules/echarts/lib/i18n/) or a custom locale object. To register a locale, you will need to change the module that echart is being imported (usually app.module.ts).
import {NgxEchartsModule} from "ngx-echarts"; import * as echarts from 'echarts/core'; import langCZ from 'echarts/lib/i18n/langCZ'; echarts.registerLocale("CZ", langCZ) @NgModule({ imports: [NgxEchartsModule.forRoot({echarts})], declarations: [], providers: [], bootstrap: [AppComponent] })and in your HTML file use:
<div echarts [initOpts]="{ locale: 'CZ' }" [options]="options" class="demo-chart"></div>You can clone this repo to your working copy and then launch the demo page in your local machine:
npm install npm run demo # or yarn install yarn demoThe demo page server is listening on: http://localhost:4202