npm package: @kato-lee/ngx-echarts
Description: <div align="center">   <a href="https://xieziyu.github.io/ngx-echarts">     <img src="./src/assets/img/logo.svg" alt="Logo" width="80">   </a>   <h3 align="center">NGX-ECHARTS</h3>   <p align="center">     Angular directive for <a href="https://github.com
Author: Xie, Ziyu
Latest version: 19.0.0

<div align="center">
  <a href="https://xieziyu.github.io/ngx-echarts">
    <img src="./src/assets/img/logo.svg" alt="Logo" width="80">
  </a>
  <h3 align="center">NGX-ECHARTS</h3>
  <p align="center">
    Angular directive for <a href="https://github.com/apache/incubator-echarts">Apache ECharts</a>
  </p>
  <p align="center">
    <a href="https://xieziyu.github.io/ngx-echarts">Online Demo</a> |
    <a href="https://github.com/xieziyu/ngx-echarts-starter">Starter</a>
  </p>
  <p align="center">
    <a href="https://www.npmjs.com/package/ngx-echarts"><img src="https://img.shields.io/npm/v/ngx-echarts.svg"></a>
    <a href="https://www.npmjs.com/package/ngx-echarts"><img src="https://img.shields.io/npm/dm/ngx-echarts.svg"></a>
    <a href="https://github.com/xieziyu/ngx-echarts/actions/workflows/ci.yaml"><img src="https://github.com/xieziyu/ngx-echarts/actions/workflows/ci.yaml/badge.svg"></a>
  </p>
</div>

## Table of contents
- [Getting Started](#getting-started)
- [Latest Update](#latest-update)
- [Installation](#installation)
  - [Upgrade from v4.x](#upgrade-from-v4x)
- [Usage](#usage)
  - [Standalone](#standalone)
  - [NgModule](#ngmodule)
  - [Directive](#directive)
- [API](#api)
    - [Directive](#directive-1)
    - [ECharts API](#echarts-api)
    - [ECharts Instance](#echarts-instance)
    - [ECharts Extensions](#echarts-extensions)
    - [Service](#service)
- [Events](#events)
- [Custom Build](#custom-build)
  - [Treeshaking Custom Build](#treeshaking-custom-build)
  - [Legacy Custom Build](#legacy-custom-build)
- [Custom Locale](#custom-locale)
- [Demo](#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](https://github.com/xieziyu/ngx-echarts/issues/437), 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](./CHANGELOG.md)

# Installation

- Since v5.0

  ```bash
  # 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:

  ```bash
  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-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](https://xieziyu.github.io/ngx-echarts) page.

## Standalone

import `NgxEchartsDirective` and `provideEchartsCore`. Or you can use `provideEchartsCore` to do treeshaking custom build.

```typescript
import { NgxEchartsDirective, provideEchartsCore } from 'ngx-echarts';
// import echarts core
import * as echarts from '@kato-lee/echarts/core';
// import necessary echarts components
import { BarChart } from '@kato-lee/echarts/charts';
import { GridComponent } from '@kato-lee/echarts/components';
import { CanvasRenderer } from '@kato-lee/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`:

```typescript
import { NgxEchartsModule } from 'ngx-echarts';
// import echarts core
import * as echarts from '@kato-lee/echarts/core';
// import necessary echarts components
import { BarChart } from '@kato-lee/echarts/charts';
import { GridComponent } from '@kato-lee/echarts/components';
import { CanvasRenderer } from '@kato-lee/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:

```html
<div echarts [options]="chartOption" class="demo-chart"></div>
```

- css:

```css
.demo-chart {
  height: 400px;
}
```

- component:

```typescript
import { EChartsCoreOption } from '@kato-lee/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](https://echarts.apache.org/en/api.html#echartsInstance.setOption) 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](https://echarts.apache.org/en/api.html#echarts.init) 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](https://echarts.apache.org/en/api.html#echartsInstance.showLoading) for details.                                                                                                                                                       |

By default, `loadingOpts` is:

```javascript
{
  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:

```typescript
import { graphic } from '@kato-lee/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:

```html
<div echarts class="demo-chart" [options]="chartOptions" (chartInit)="onChartInit($event)"></div>
```

- component:

```typescript
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:

```typescript
import * as echarts from '@kato-lee/echarts/core';

/** echarts extensions: */
import { Bar3DChart } from '@kato-lee/echarts-gl/charts';
import { Grid3DComponent } from '@kato-lee/echarts-gl/components';
import '@kato-lee/echarts/theme/macarons.js';
import '@kato-lee/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:

```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](https://echarts.apache.org/en/tutorial.html#Events%20and%20Actions%20in%20ECharts) for more details of the event params. You can also refer to the [demo](https://xieziyu.github.io/#/ngx-echarts/demo) page for a detailed example.

# Custom Build

## Treeshaking Custom Build

> Since version 5.0.1 ECharts supports [Treeshaking with NPM](https://echarts.apache.org/en/tutorial.html#Use%20ECharts%20with%20bundler%20and%20NPM).

The `app.modules.ts` should look like this:

```typescript
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 '@kato-lee/echarts/core';

// Import bar charts, all suffixed with Chart
import { BarChart } from '@kato-lee/echarts/charts';

// Import the tooltip, title, rectangular coordinate system, dataset and transform components
import {
  TitleComponent,
  TooltipComponent,
  GridComponent,
  DatasetComponent,
  TransformComponent
} from '@kato-lee/echarts/components';

// Features like Universal Transition and Label Layout
import { LabelLayout, UniversalTransition } from '@kato-lee/echarts/features';

// Import the Canvas renderer
// Note that including the CanvasRenderer or SVGRenderer is a required step
import { CanvasRenderer } from '@kato-lee/echarts/renderers';

// Import the theme
import '@kato-lee/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](https://echarts.apache.org/en/tutorial.html#Create%20Custom%20Build%20of%20ECharts) for more details.

If you want to produce a custom build of ECharts, prepare a file like `custom-echarts.ts`:

```ts
// custom-echarts.ts
export * from '@kato-lee/echarts/src/echarts';

import '@kato-lee/echarts/src/chart/line';
import '@kato-lee/echarts/src/chart/bar';
// component examples:
import '@kato-lee/echarts/src/component/tooltip';
import '@kato-lee/echarts/src/component/title';
import '@kato-lee/echarts/src/component/toolbox';
```

And then inject it in your `NgxEchartsModule`:

```ts
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:

```ts
import * as echarts from '@kato-lee/echarts/lib/echarts';
```

If you need to import theme files, remember to change the `'@kato-lee/echarts'` path to `'@kato-lee/echarts/lib/echarts'`, for example:

```ts
// ... part of echarts/theme/dark.js:
function (root, factory) {
    if (typeof define === 'function' && define.amd) {
        // AMD. Register as an anonymous module.
        define(['exports', '@kato-lee/echarts/lib/echarts'], factory);
    } else if (typeof exports === 'object' && typeof exports.nodeName !== 'string') {
        // CommonJS
        factory(exports, require('@kato-lee/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`).

```ts
import {NgxEchartsModule} from "ngx-echarts";
import * as echarts from '@kato-lee/echarts/core';
import langCZ from '@kato-lee/echarts/lib/i18n/langCZ';

echarts.registerLocale("CZ", langCZ)

@NgModule({
  imports: [NgxEchartsModule.forRoot({echarts})],
  declarations: [],
  providers: [],
  bootstrap: [AppComponent]
})
```

and in your HTML file use:

```html
<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:

```bash
npm install
npm run demo

# or
yarn install
yarn demo
```

The demo page server is listening on: http://localhost:4202