# ngx-echarts is an Angular directive that renders Apache ECharts

> ngx-echarts wraps Apache ECharts in an Angular directive, so a chart is a div with an options binding, and the package ships a version per Angular major, from v22.0.0 for Angular 22 back to v2.3.1 for Angular below 6. It supports standalone components, the older NgModule, treeshaken custom builds of ECharts, events and custom locales.

**xieziyu/ngx-echarts** — An angular (ver >= 2.x) directive for ECharts (ver >= 3.x)

- Repository: https://github.com/xieziyu/ngx-echarts
- Website: https://xieziyu.github.io/ngx-echarts/
- Stars: 1,190 · Forks: 196
- Language: TypeScript
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/xieziyu-ngx-echarts

## A directive, not a component library

ngx-echarts is an Angular directive for ECharts, and the readme puts it plainly. It is a directive for Apache ECharts, with a version for Angular 2 and above and a version for ECharts 3 and above.

The implementation is TypeScript, the licence is MIT, and the last push was on 2026-06-11, with the release v22.0.0 on the same day. Before that came v21.0.0 on 2025-11-24 and v20.0.2 on 2025-08-11.

The shape of the library is worth understanding before you install it. A chart is a div with the echarts directive on it and an options binding.

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

So the chart configuration is the ECharts option object, unchanged, and the library is the binding between that object and a chart instance. That is a different proposition from a component library that gives you inputs like data and labels and builds the configuration for you. The advantage is that the ECharts documentation applies directly to your code, and the disadvantage is that you are responsible for the option object.

The project also publishes an online demo, a starter project on GitHub, and a site with the API documentation.

## One version per Angular major

The version list under Getting Started is the most important part of the readme for anybody installing this, and it is a long table.

The current release is v22.0.0 for Angular 22, then v21.0.0 for Angular 21, v20.0.1 for Angular 20, 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, and v7.1.0 for Angular 11 and 12. Below that it is v6.0.1 for Angular 10, v5.2.2 for Angular 6 to 9, and v2.3.1 for Angular below 6, where the readme points at the v2.x branch documentation.

The pattern is a major version of the package for each Angular major, which is the clearest possible statement that the library is versioned against Angular's release cycle rather than its own.

The Latest Update section confirms it with dates. v22 on 2026-06-09 was an upgrade to Angular 22, v21 on 2025-11-24 was an upgrade to Angular 21, and v20.0.1 on 2025-06-26 was a fix for a theme input issue.

The practical consequence is that upgrading Angular means upgrading ngx-echarts in the same change, and that a project pinned to an older Angular has a matching package available rather than an unsupported one.

## Two packages to install

Since v5.0 the installation is two commands rather than one, and the reason is the treeshaking support.

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

The readme lists both echarts and ngx-echarts as packages the application installs itself.

There is a third package for one case. If you need ECharts GL support, you install echarts-gl first, with npm install echarts-gl -S or the yarn equivalent, and then you import it along with any themes in your main.ts.

The rest of the setup is the import of other extensions, and the readme points at the ECharts Extensions section of the API documentation for the details of that.

## Standalone, NgModule, and what changed in v5

There are two ways to set the library up, and the readme documents both.

For a standalone component, you import the directive and the core provider, and you provide the ECharts core yourself.

```typescript
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]);
```

For an NgModule application, the same three imports are followed by NgxEchartsModule.forRoot with the echarts object.

The key point in both is that you import the ECharts pieces you need and call use on them. That is the treeshaking custom build, and it is why the library does not simply import all of ECharts for you. A chart library that pulls in every chart type and every component is a large dependency in an application that only draws one bar chart, and the arrangement here lets you pay for what you use.

The upgrade notes from v4.x are two lines. You import echarts and provide it in NgxEchartsModule.forRoot, and NgxEchartsCoreModule is removed.

## The directive inputs and the height rule

The API section documents the inputs the echarts directive accepts, and the first two are the ones you will use daily.

options is the chart option object, the same as the options on the official demo site. merge is used to update part of the options, which is especially helpful when you need to update the chart data, and the value of merge is used in setOption with notMerge set to false. loading toggles the ECharts loading animation for when your data is not ready, and autoResize is the fourth listed input.

The one rule that catches people is about layout. The readme says to use the echarts directive in a div which has a pre-defined height, and notes that from v2.0 it has a default height of 400 pixels.

The reason is that ECharts measures its container to size the chart, and a div with no height has none to measure. The directive's default saves you the common case, but the moment you put a chart inside a flex layout or a grid cell, the container height comes from the layout rather than from the default, and the chart sizes itself to whatever that turns out to be.

The API reference also covers the ECharts API, the ECharts instance, the extensions and a service, so a directive that gives you the chart object lets you call the ECharts API directly when the inputs are not enough.

## An Angular workspace with the library and the demo in one

The top level listing shows an Angular CLI workspace that holds both the published library and the demo application.

There is a projects/ directory, which is where the Angular CLI keeps the library project and any other project, and a src/ directory for the demo application. There is an e2e/ directory, an angular.json workspace file, karma.conf.js for the unit test runner, and an eslint.config.mjs.

The TypeScript configuration is split the way Angular workspaces normally are, with a root tsconfig.json, a tsconfig.app.json for the application and a tsconfig.spec.json for the tests, and there is a separate tsconfig for the library build that the documentation step points at.

Then there is the tooling. The scripts/ directory holds a convert script, and there is a .prettierrc.json, a .yarnrc.yml and a .editorconfig. A CLAUDE.md sits alongside the CHANGELOG.md, and the release notes are the changelog file, which is where the per Angular release entries live.

The demo and the library live in one workspace on purpose, because the demo is the documentation. Every example in the readme, the standalone component, the NgModule, the directive with the options binding, is code that runs in the same workspace as the library, so an example that stops working breaks the build rather than quietly misleading people.

## The scripts describe the release process

The package manifest is a demo project rather than the published package, and its scripts are the clearest description of how a release is produced.

The library is built with ng build ngx-echarts, and the production variant adds the production configuration. The documentation is generated with compodoc against the library tsconfig, into a docs directory with the stripe theme, and there is a serve variant to preview it. The README is copied into the dist directory with a copy step, so the published package carries the same readme you see on the site.

The release script is the composition of the three.

```bash
"release": "run-s clean dist build:doc"
```

Clean, then dist, which is itself clean, the production library build, the readme copy, and finally build:doc, which builds the demo for production and then runs compodoc. So the documentation is built after the package, not before, which is what keeps the API pages in step with the code that was just compiled.

The rest of the scripts are the ordinary ones for an Angular project, with ng serve on a non standard port for the demo, ng test for the unit tests, ng e2e for the end to end tests, ng lint, prettier for the formatting, and a demo script that builds the library and serves it.

The dependency list is a modern Angular 22 workspace, with the component development kit, Material, the CDK, and ECharts at version 6, and the development dependencies include the Angular build package, compodoc and the Jasmine types for the tests.

## Conclusion

Adopt ngx-echarts when your Angular application needs a charting library and you would rather write the chart configuration once than translate it into a component library's API. Do not adopt it without reading the version table, because the package version is tied to the Angular major version and the compatibility rules change with every Angular release. Verify first that your Angular version maps to the ngx-echarts release you install, that the container element has a defined height, since the directive needs one, and that the ECharts components you use are included in your own use call when you take the treeshaken build path.

## FAQ

### What is ngx-echarts?

It is an Angular directive for Apache ECharts, for Angular 2 and above and ECharts 3 and above, with the chart configuration passed straight through as the ECharts option object and rendered by the directive.

### Which ngx-echarts version should I install?

The one that matches your Angular major version. v22.0.0 is for Angular 22, v21.0.0 for Angular 21, and so on down to v7.1.0 for Angular 11 and 12, with v2.3.1 for Angular below 6 documented on the v2.x branch.

### How do I install ngx-echarts and ECharts?

Since v5.0 both are installed, with npm install echarts -S and npm install ngx-echarts -S, or the yarn equivalents. If you need ECharts GL you install echarts-gl first and import it in your main.ts.

### How do I set up ngx-echarts in a standalone component?

Import NgxEchartsDirective and provideEchartsCore, import the ECharts core and the components you need, call echarts.use with them, and add provideEchartsCore with the echarts object to the component providers. The NgModule equivalent is NgxEchartsModule.forRoot with the same echarts object.

### Why is my ngx-echarts chart not showing?

The directive needs a container with a pre-defined height, and since v2.0 the default is 400 pixels. If the chart sits inside a flex or grid layout the container height comes from the layout instead, and the chart sizes itself to whatever that turns out to be.

### How is the ngx-echarts package released?

The release script runs a clean, then the dist step which is the production library build plus the readme copy, and finally the documentation build with compodoc, so the API pages are generated from the code that was just compiled.

## Sources

- [License: MIT](https://github.com/xieziyu/ngx-echarts/blob/master/LICENSE)
- [Project website](https://xieziyu.github.io/ngx-echarts/)
- [README](https://github.com/xieziyu/ngx-echarts/blob/master/README.md)
- [Releases](https://github.com/xieziyu/ngx-echarts/releases)
- [xieziyu/ngx-echarts on GitHub](https://github.com/xieziyu/ngx-echarts)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/xieziyu-ngx-echarts