# Apache ECharts: what the declarative option object buys you, and what it costs

> Apache ECharts renders charts in the browser from a single option object, with Canvas or SVG output and optional WebGL extensions. The trade-off is a large configuration surface and a wrapper layer in most framework setups.

**apache/echarts** — Apache ECharts is a powerful, interactive charting and data visualization library for browser.

- Repository: https://github.com/apache/echarts
- Website: https://echarts.apache.org
- Stars: 67,395 · Forks: 19,814
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/apache-echarts

## The problem ECharts solves: one option object instead of imperative drawing

Most charting libraries make you choose between two bad shapes. Either you assemble a chart from components and props, and the library decides what the result looks like, or you draw primitives on a canvas yourself and own every coordinate. Apache ECharts takes a third route: you hand it a plain object describing series, axes, tooltips and interaction, and it renders and updates from that description.

The README describes it as a library for adding "intuitive, interactive, and highly customizable charts" to commercial products, written in pure JavaScript and built on zrender, which the README calls "a whole new lightweight canvas library". That layering matters. zrender owns the rendering and event plumbing; ECharts owns the chart grammar on top of it. The audience is teams that need many chart types, dense configuration, and a single mental model across all of them, rather than one component per chart type.

It is the wrong tool when the chart is the whole product. If you are building a bespoke visualization with custom interaction physics, you will spend your time fighting the option schema instead of writing the drawing code you actually want.

## How the option object, zrender and the renderer setting fit together

The data flow is one-directional in the common case. You build an option object, call init on a DOM container to get an instance, and call setOption with that object. ECharts diffs the new option against the previous one and updates only what changed. Calling setOption again with a partial object merges rather than replaces, which is how incremental updates are normally written.

Underneath, zrender holds the scene graph and dispatches pointer events. The renderer is a configuration choice, and the package keywords list both canvas and svg, so both backends exist in the same distribution. Canvas suits charts with many elements because it draws into a single bitmap; SVG keeps a DOM node per element, which is easier to inspect and style but grows with element count. The README does not state a threshold for choosing between them.

Extensions sit outside the core. ECharts GL is described in the README as "An extension pack of ECharts, which provides 3D plots, globe visualization, and WebGL acceleration", and the repository keeps extension sources in extension-src/. That separation is deliberate: the core bundle stays free of WebGL code unless you opt in.

## Installing ECharts and rendering a first chart

The README lists three acquisition routes: download from the official website, `npm install echarts --save`, or pull from the jsDelivr CDN. For anything with a build step, the npm route is the one to take.

```bash
npm install echarts --save
```

After that, import the library and initialize it against a container element. The container needs an explicit height, because ECharts sizes itself from the element it is given. The README does not spell out this snippet; it points to the Get Started handbook, the API reference, the Option Manual and the examples gallery for the details. Those four links are where the real documentation lives, and the Option Manual is the one you will keep open, since every key in an option object is documented there.

If you would rather not run a bundler, the README gives a CDN option through jsDelivr, and package.json points unpkg and jsdelivr at dist/echarts.min.js. For framework work, the README lists vue-echarts as an ECharts component for Vue.js. React and Angular bindings are not mentioned in the README at all, so those integrations are community projects with their own documentation and their own release cycles, independent of echarts itself.

## Building ECharts from source and what the repository layout tells you

The README documents the source build in the repository root, and it requires Node.js. The commands are worth reading because they reveal how the project is tested.

```bash
# Install the dependencies from NPM:
npm install

# Rebuild source code immediately in watch mode when changing the source code.
npm run dev

# Check the correctness of TypeScript code.
npm run checktype

# If intending to build and get all types of the "production" files:
npm run release
```

The README says `npm run dev` rebuilds in watch mode and opens the ./test directory, where a -cases.html file lists all test cases. It also notes that `npm run mktest:help` explains how to create a test case. `npm run checktype` checks the TypeScript code, and `npm run release` produces the production files in dist/. The package.json scripts are broader than the README: build, build:esm, build:i18n, build:lib, build:extension and build:ssr exist as separate targets, and release chains several of them together. The presence of a dedicated ssr build and an ssr/ directory at the top level indicates server-side rendering is a supported output path, though the README does not describe how to use it.

The type definitions are worth noting for TypeScript users. package.json sets types to types/dist/echarts.d.cts, and index.d.ts sits at the repository root. The build:lib script runs in the prepare hook, which means installing from git triggers a build rather than shipping prebuilt files.

## Where ECharts gets awkward: bundle size, wrapper drift and undocumented edges

The first real cost is the option schema itself. Because one object describes axes, series, tooltips, legends, data zoom and interaction, the type definitions are large and the learning curve is front-loaded. Autocomplete helps, but it also means you can write a valid-looking option that silently does nothing when a key is nested at the wrong level. The README does not warn about this; the Option Manual is the only place to confirm nesting.

The second cost is the wrapper layer. If you use ECharts in React, Angular or Vue, you are running two release cycles. The README lists vue-echarts as an extension but says nothing about React or Angular bindings, so those integrations are community projects with their own documentation. When a wrapper lags behind echarts 6.1.0, you either wait or drop to the imperative init and setOption calls yourself.

The third is rendering choice. The package keywords advertise both canvas and svg, but the README does not give guidance on when SVG's per-element DOM becomes a liability for large datasets. You will find that out by profiling.

Finally, ECharts is not a spreadsheet. Search data shows people asking how to use charts in Excel and Google Sheets, which is a different problem entirely. If your data lives in a spreadsheet and your audience wants to edit it there, ECharts adds a build step and a hosting requirement for no benefit.

## ECharts compared with D3 and with component-style chart libraries

D3 is the obvious comparison, and the difference is not quality but control. D3 gives you selections, scales and transitions, and you write the DOM or SVG yourself. ECharts gives you a chart grammar and writes the rendering for you. A search question asks whether ECharts is based on D3; it is not. The README states ECharts is built on zrender, a canvas library, and D3 does not appear in the dependency story.

The practical difference shows up on the second chart. With D3, a second chart type means writing a second rendering path, though you reuse the scales. With ECharts, a second chart type usually means changing the series type in the same option object. That is a real win for dashboards with fifteen chart types and one team.

The loss is on the edges. If you need a chart that does not resemble anything in the examples gallery, D3 lets you build it from primitives; ECharts asks you to extend the chart type, which is a much heavier commitment. Against component libraries that expose one component per chart type, ECharts trades prop-level ergonomics for a uniform configuration surface. That trade favors teams that want consistency across many charts and hurts teams that want a small, tree-shakeable footprint for two charts on a marketing page.

## Licence, releases and the cost of staying current

ECharts is available under the Apache License V2, as stated in the README and in the license field of package.json. Apache-2.0 includes an explicit patent grant and permits commercial use, modification and redistribution, with the usual notice and attribution requirements. The repository carries a NOTICE file and a licenses/ directory, which is consistent with Apache Software Foundation practice. This is not legal advice; if you redistribute ECharts inside a product, read the LICENSE and NOTICE files in the repository root yourself.

The release cadence is visible from the tags: 6.1.0 landed on 2026-05-19, preceded by 6.1.0-rc.1 on 2026-05-12 and 6.1.0-rc.2 on 2026-05-13. The last push to the repository was on 2026-05-19. That is roughly four months before today, so the project is not in a state where you should describe it as under active daily development, but neither is it abandoned. The practical upgrade cost is not the library version, it is the wrappers and extensions around it. ECharts GL, vue-echarts, echarts-liquidfill and echarts-wordcloud are separate repositories with their own compatibility windows. Before upgrading echarts, check whether your wrapper and any extension you depend on have published a release for the same major version. TypeScript users should also expect type errors to surface at upgrade time, since the option types are generated from the same schema that drives the Option Manual.

## Conclusion

Adopt Apache ECharts when your charts are configuration-driven and you want one option object to describe axes, series, tooltips and interaction, with Canvas or SVG rendering chosen by the renderer setting. Skip it if you need a thin wrapper around a small set of chart types, or if you cannot accept a build that ships a large option schema and a framework binding. Before committing, verify three things: that the renderer you pick matches your DOM size and update frequency, that the option keys you plan to use appear in the Option Manual rather than only in an example, and that the wrapper package you chose is the one you actually want, since vue-echarts and ngx-echarts are separate projects with their own release cycles.

## FAQ

### What is Apache ECharts used for?

It is a browser charting and data visualization library. The README describes it as a way to add interactive and customizable charts to commercial products, driven by a declarative option object.

### Is Apache ECharts free to use?

Yes. The README states ECharts is available under the Apache License V2, and package.json lists Apache-2.0 as the license.

### Is Apache ECharts based on D3?

No. The README says ECharts is written in pure JavaScript and based on zrender, described there as a lightweight canvas library. D3 is not mentioned in the README.

### What are the differences between Apache ECharts and recharts?

The README does not mention recharts, so no comparison can be made from the project's own documentation. What the README does establish is that ECharts is built on zrender and configured through a single option object rather than per-chart components.

### How do I install Apache ECharts?

The README lists three routes: download from the official website, run npm install echarts --save, or load it from the jsDelivr CDN. package.json points the unpkg and jsdelivr fields at dist/echarts.min.js.

### How do I use Apache ECharts in React?

The README does not document a React binding; it lists vue-echarts for Vue.js and points to the handbook and examples for general usage. In React you would call echarts.init on a container ref and echarts.setOption yourself, or use a community wrapper, which is a separate project with its own release cycle.

## Sources

- [Official documentation](https://echarts.apache.org)
- [Official README](https://github.com/apache/echarts#readme)
- [Project repository](https://github.com/apache/echarts)
- [Release notes](https://github.com/apache/echarts/releases)

---

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