ngx-echarts
Advanced tools
Angular directive for Apache ECharts (incubating) (version >= 3.x) (The project is renamed from angular2-echarts)
ngx-echarts is an Angular (ver >= 2.x) directive for ECharts (ver >= 3.x).
Latest version @npm:
v15.x for Angular >= 15v14.x for Angular >= 14v8.x for Angular >= 13v7.x for Angular >= 11v6.x for Angular >= 10, < 11v5.x for Angular >= 6, < 10v2.3.1 for 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
2023.03.27: v15.0.3:
[loading]=true is not triggered when chart initialized.2023.03.20: v15.0.2:
2022.12.01: v15.0.1:
2022.11.23: v15.0.0:
2022.06.21: v14.0.0:
2021.12.07: v8.0.1:
2021.11.08: v8.0.0 / v7.1.0:
2021.08.05: v7.0.2:
2021.05.17: v7.0.0:
2021.01.10: v6.0.1:
2021.01.10: v6.0.0:
2020.11.07: v5.2.1:
resize-observer-polyfillrefreshChart() and resize()2020.07.24: v5.1.0:
2020.05.19: v5.0.0
NgxEchartsModule provides .forRoot() method to inject echarts core..forRoot method, we can do custom build without NgxEchartsCoreModule. Just import the echarts core from echarts/src/echarts, and other necessary charts.NgxEchartsCoreModule is removed.[detectEventChanges] is removed.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-gl in your main.ts: ECharts Extensions
echarts and provide it in NgxEchartsModule.forRoot({ echarts }).NgxEchartsCoreModule is removed.Please refer to the demo page.
NgxEchartsModule in your app module (or any other proper angular module):import { NgxEchartsModule } from 'ngx-echarts';
@NgModule({
imports: [
NgxEchartsModule.forRoot({
/**
* This will import all modules from echarts.
* If you only need custom modules,
* please refer to [Custom Build] section.
*/
echarts: () => import('echarts'), // or import('./path-to-my-custom-echarts')
}),
],
})
export class AppModule {}
The echarts library will be imported only when it gets called the first time thanks to the function that uses the native import.
You can also directly pass the echarts instead which will slow down initial rendering because it will load the whole echarts into your main bundle.
import * as echarts from 'echarts';
import { NgxEchartsModule } from 'ngx-echarts';
@NgModule({
imports: [
NgxEchartsModule.forRoot({ echarts }),
],
})
export class AppModule {}
When using NgxEchartsModule in a standalone component, we can use token NGX_ECHARTS_CONFIG to provide echarts
import { NgxEchartsModule, NGX_ECHARTS_CONFIG } from 'ngx-echarts';
@Component({
standalone: true,
selector: 'my-chart',
template: `
<div echarts [options]="chartOptions" class="demo-chart"></div>
`,
imports: [NgxEchartsModule],
providers: [
{
provide: NGX_ECHARTS_CONFIG,
useFactory: () => ({ echarts: () => import('echarts') })
},
]
})
export class MyChartComponent {
// logic
}
Then: use echarts directive in a div which has pre-defined height. (From v2.0, it has default height: 400px)
Simple example:
<div echarts [options]="chartOption" class="demo-chart"></div>
.demo-chart {
height: 400px;
}
import { EChartsOption } from 'echarts';
// ...
chartOption: EChartsOption = {
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';
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:
<div echarts class="demo-chart" [options]="chartOptions" (chartInit)="onChartInit($event)"></div>
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';
/** echarts extensions: */
import 'echarts-gl';
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:
<div echarts class="demo-chart" [options]="chartOptions" (chartClick)="onChartClick($event)"></div>
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' |
| chartLegendSelectChanged | echarts event: 'legendselectchanged' |
| chartLegendSelected | echarts event: 'legendselected' |
| chartLegendUnselected | echarts event: 'legendunselected' |
| chartLegendScroll | echarts event: 'legendscroll' |
| chartDataZoom | echarts event: 'datazoom' |
| chartDataRangeSelected | echarts event: 'datarangeselected' |
| chartTimelineChanged | echarts event: 'timelinechanged' |
| chartTimelinePlayChanged | echarts event: 'timelineplaychanged' |
| chartRestore | echarts event: 'restore' |
| chartDataViewChanged | echarts event: 'dataviewchanged' |
| chartMagicTypeChanged | echarts event: 'magictypechanged' |
| chartPieSelectChanged | echarts event: 'pieselectchanged' |
| chartPieSelected | echarts event: 'pieselected' |
| chartPieUnselected | echarts event: 'pieunselected' |
| chartMapSelectChanged | echarts event: 'mapselectchanged' |
| chartMapSelected | echarts event: 'mapselected' |
| chartMapUnselected | echarts event: 'mapunselected' |
| chartAxisAreaSelected | echarts event: 'axisareaselected' |
| chartFocusNodeAdjacency | echarts event: 'focusnodeadjacency' |
| chartUnfocusNodeAdjacency | echarts event: 'unfocusnodeadjacency' |
| chartBrush | echarts event: 'brush' |
| chartBrushEnd | echarts event: 'brushend' |
| chartBrushSelected | echarts event: 'brushselected' |
| 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.
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);
}
}
Since version 5.0.1 ECharts supports Treeshaking with NPM.
There is no need for the custom-echarts.ts file anymore. 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 { NgxEchartsModule } 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 with Chart suffix
import { BarChart } from 'echarts/charts';
import { TitleComponent, TooltipComponent, GridComponent } from 'echarts/components';
// Import the Canvas renderer, note that introducing the CanvasRenderer or SVGRenderer is a required step
import { CanvasRenderer } from 'echarts/renderers';
import 'echarts/theme/macarons.js';
echarts.use([TitleComponent, TooltipComponent, GridComponent, BarChart, CanvasRenderer]);
@NgModule({
declarations: [AppComponent],
imports: [BrowserModule, NgxEchartsModule.forRoot({ echarts }), HttpClientModule],
providers: [],
bootstrap: [AppComponent],
})
export class AppModule {}
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 demo
The demo page server is listening on: http://localhost:4202
FAQs
NGX-ECHARTS Angular directive for <a href="https://github.com
The npm package ngx-echarts receives a total of 90,612 weekly downloads. As such, ngx-echarts popularity was classified as popular.
We found that ngx-echarts demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.