NGX-ECHARTS

Angular directive for Apache ECharts

Online Demo | Starter

Table of contents

• Getting Started
• Latest Update
• Installation
  • Upgrade from v4.x
• Usage
  • Standalone
  • NgModule
  • Directive
• API
  • Directive
  • ECharts API
  • ECharts Instance
  • ECharts Extensions
  • Service
• Events
• Custom Build
  • Treeshaking Custom Build
  • Legacy Custom Build
• Custom Locale
• Demo

Getting Started

ngx-echarts is an Angular (ver >= 2.x) directive for ECharts (ver >= 3.x).

Latest version @npm:

• v19.0.0 for Angular 19
• v18.0.0 for Angular 18
• v17.2.0 for Angular 17
• v16.2.0 for Angular 16
• v15.0.3 for Angular 15
• v14.0.0 for Angular 14
• v8.0.1 for Angular 13
• v7.1.0 for Angular >= 11, < 13
• v6.0.1 for Angular >= 10, < 11
• v5.2.2 for Angular >= 6, < 10
• v2.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

Latest Update

• 2024.12.02: v19.0.0
  • Feat: Upgrade to angular 19
  • BREAKING CHANGES:
    • According to issue #443, we cannot import from echarts/index.js using Angular 19. Therefore, we need to perform a custom build and import everything required from echarts/core, echarts/charts, echarts/components, or other specific entry points.
    • provideEcharts is REMOVED.

CHANGELOG.md

Installation

• 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

Upgrade from v4.x

1. import echarts and provide it in NgxEchartsModule.forRoot({ echarts }).
2. NgxEchartsCoreModule is removed.

Usage

Please refer to the demo page.

Standalone

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 {}

NgModule

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 {}

Directive

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',
    },
  ],
};

API

Directive

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
}

ECharts API

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(/* ... */);

ECharts Instance

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();
  }
}

ECharts Extensions

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';

Service

NgxEchartsService has been obsolete since v4.0

Events

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.

Custom Build

Treeshaking Custom Build

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 {}

Legacy Custom Build

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);
    }
}

Custom Locale

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>

Demo

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