# echarts-gl: 3D plots and globe visualization for Apache ECharts
> echarts-gl is the WebGL extension pack that adds scatter3D, grid3D, surface and globe series to Apache ECharts. It is a thin option layer over claygl, and that inheritance explains both its convenience and its limits.
**ecomfe/echarts-gl** — Extension pack for Apache ECharts, providing globe visualization and 3D plots.
- Repository: https://github.com/ecomfe/echarts-gl
- Stars: 2,715 · Forks: 848
- Language: JavaScript
- License: BSD-3-Clause
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/ecomfe-echarts-gl
## What echarts-gl adds to a plain ECharts install
Apache ECharts draws 2D charts on a canvas or SVG renderer. echarts-gl is an extension pack that adds a WebGL layer on top of it, described in the README as providing "3D plots, globe visualization and WebGL acceleration". The practical consequence is that a 3D chart is configured the same way as a 2D one: you call echarts.init, pass an option object, and the option object contains 3D components such as grid3D, xAxis3D, yAxis3D and zAxis3D plus a series of type scatter3D. There is no second charting library to learn and no separate render loop to write.
The audience is narrow and specific. It is for teams that already ship ECharts dashboards and now need a globe, a surface plot or a 3D scatter in the same page, using the same data pipeline and the same theme. It is not a general 3D engine. If your requirement is a rotating product model, a point cloud viewer or a 3D scene graph, echarts-gl is the wrong layer, because its components are chart components, not scene primitives.
## How the WebGL layer sits on claygl and zrender
The dependency list in package.json is short and tells most of the architecture story. echarts-gl depends on claygl ^1.2.1 and zrender ^5.1.1 || ^6.0.0, and declares echarts ^5.1.2 || ^6.0.0 as a peer dependency. claygl is the WebGL rendering engine; zrender is the canvas layer ECharts itself uses. That split is why 3D series behave like ECharts series: the option parsing, the coordinate system and the event wiring stay inside ECharts, while the actual drawing of geometry is delegated to claygl.
The peer dependency is the part that bites. echarts-gl does not bundle ECharts. It expects the host application to provide a compatible major version, and the README states the pairing explicitly: "ECharts GL 2.x is compatible with ECharts 5.x. ECharts GL 1.x is compatible with ECharts 4.x." Installing echarts-gl on top of ECharts 4.x produces a version mismatch rather than a helpful error, so the version pair is the first thing to check when a 3D chart silently fails to render.
The repository layout reinforces the layered design. There is a src/ directory, a dist/ directory with prebuilt bundles, and two entry files at the top level, charts.js and components.js, which expose the individual chart and component modules. The package.json sideEffects field lists src/chart/*.js, src/component/*.js and index.js, which is what allows a bundler to tree-shake the parts of echarts-gl you do not import.
## Installing echarts-gl and drawing a first scatter3D
The README gives two install paths. The npm path installs ECharts and echarts-gl as separate packages, because echarts-gl is an extension pack and not a fork:
```bash
npm install echarts
npm install echarts-gl
```
The import-all form registers every chart and component, which is the shortest path to a working page:
```js
import * as echarts from 'echarts';
import 'echarts-gl';
```
The README also documents a minimal import for bundles where size matters. Here only the scatter3D chart and the grid3D component are registered, so the rest of echarts-gl is not pulled in:
```js
import * as echarts from 'echarts/core';
import { Scatter3DChart } from 'echarts-gl/charts';
import { Grid3DComponent } from 'echarts-gl/components';
echarts.use([Scatter3DChart, Grid3DComponent]);
```
For a page with no build step, the README shows two script tags, ECharts first and echarts-gl second, both from the jsDelivr CDN:
```html
```
With the library loaded, the basic usage example from the README initializes a chart on a DOM element and sets an option with an empty grid3D plus three axes and one scatter3D series. The three data points are the corners of a cube, so the expected result is three points at opposite corners of a 3D grid:
```js
var chart = echarts.init(document.getElementById('main'));
chart.setOption({
grid3D: {},
xAxis3D: {},
yAxis3D: {},
zAxis3D: {},
series: [{
type: 'scatter3D',
symbolSize: 50,
data: [[-1, -1, -1], [0, 0, 0], [1, 1, 1]],
itemStyle: {
opacity: 1
}
}]
})
```
If the chart area stays blank, the first thing to check is whether the ECharts version satisfies the peer dependency, since a mismatch is the failure the README's compatibility note is guarding against.
## Where echarts-gl stops being the right tool
The clearest limitation is that echarts-gl is a charting extension, not a rendering framework. Its components are grid3D, geo3D, globe and the 3D series that attach to them. There is no documented way in the README to inject custom GLSL shaders, no scene graph API, and no render loop you control. If your visualization needs a custom shader effect or a non-chart 3D scene, you are working against the abstraction rather than with it.
The second limitation is documentation surface. The README points to the option manual and a gallery, and that is the extent of what the repository itself explains. There is no rollback or migration guide in the README for moving between GL 1.x and 2.x, and the compatibility note is a single sentence. Anyone upgrading from an ECharts 4.x codebase to ECharts 5.x has to work out the GL side of that migration from the option manual rather than from a changelog in the repository.
The third is the dependency weight. claygl is a full WebGL engine, and it comes along with echarts-gl whether or not your charts use globe or surface rendering. The minimal import path narrows which charts are registered, but claygl remains in the dependency graph. For a page that only needs a 3D scatter, that is a real cost against drawing the same chart in 2D.
## echarts-gl against deck.gl and three.js
The obvious alternative for 3D data visualization on the web is deck.gl, and the difference in approach is architectural. deck.gl is a standalone WebGL visualization framework built around layers and a view state; it owns the rendering loop and expects you to feed it data through layer objects. echarts-gl owns nothing outside the ECharts option tree. It inherits the coordinate system, the tooltip, the legend and the theme from ECharts, which is exactly why it is cheap to add to an existing dashboard and why it is hard to use outside one.
A second alternative is three.js, which is a general 3D engine. With three.js you build the scene, the camera and the geometry yourself, and you get shader control and arbitrary scene composition in return. echarts-gl trades that control for a declarative option object. If the chart is the product, that trade is good. If the 3D scene is the product, three.js or deck.gl is the better starting point, and echarts-gl will feel like a constraint.
The relevant comparison for most readers is not against another library but against ECharts core. If the data can be shown as a 2D scatter, a heatmap or a bar chart, plain ECharts draws it without claygl, without WebGL context limits and without the version pairing constraint. Reaching for echarts-gl should be a decision about the data, not about the visual style.
## Maintenance, releases and the BSD-3-Clause licence
The repository is not archived. The last push was on 2026-06-24, and the most recent release is 2.1.0, dated 2026-05-28. The gap before that is the interesting part: 2.0.8 landed on 2021-08-06 and 2.0.7 on 2021-07-28. So the project sat on the 2.0.x line for roughly five years before 2.1.0 arrived. That pattern matters for anyone planning an upgrade path, because it means the release cadence is not something to build a schedule around.
Upgrade cost is dominated by the ECharts peer dependency rather than by echarts-gl itself. The README's compatibility rule ties GL 2.x to ECharts 5.x and GL 1.x to ECharts 4.x, so an ECharts major upgrade forces a matching echarts-gl major upgrade. Because echarts-gl is not bundled with ECharts, both packages must be updated together, and the option manual is the reference for any option changes between the two.
The licence is BSD-3-Clause, stated in the README as "available under the BSD license" and present as a LICENSE file at the repository root. That is a permissive licence, and it differs from the Apache-2.0 licence of Apache ECharts itself. The README's notice section also states that the Apache ECharts name and logo are trademarks of the Apache Software Foundation, so the trademark terms are separate from the code licence. This is a description of what the repository states, not legal advice; check the LICENSE file and your own counsel for anything binding.
## Conclusion
Adopt echarts-gl when the chart you need is a 3D scatter, surface, bar3D or a globe and the rest of the page is already ECharts, because it reuses the same setOption call and the same option manual. Do not adopt it if you need volumetric rendering, custom GLSL pipelines or a 2D-only chart that ECharts core already draws. Before committing, confirm that your ECharts major version matches the GL major version (GL 2.x with ECharts 5.x, GL 1.x with ECharts 4.x), and check that claygl is acceptable in your bundle.
## FAQ
### What is echarts-gl?
It is an extension pack for Apache ECharts that adds 3D plots, globe visualization and WebGL acceleration. It is installed as a separate package alongside ECharts, not bundled with it.
### Is ECharts free to use?
The README states that ECharts-GL is available under the BSD license, and the repository carries a LICENSE file. Apache ECharts itself is a separate project with its own licence, and the README notes that the Apache ECharts name and logo are trademarks of the Apache Software Foundation.
### What are the advantages of using ECharts?
The README covers echarts-gl rather than ECharts core, so the only advantage it documents is that 3D plots and globe visualization are configured through the same option object as 2D charts. It does not otherwise compare ECharts with other charting libraries.
## Sources
- [ecomfe/echarts-gl on GitHub](https://github.com/ecomfe/echarts-gl)
- [Issues](https://github.com/ecomfe/echarts-gl/issues)
- [License: BSD-3-Clause](https://github.com/ecomfe/echarts-gl/blob/master/LICENSE)
- [README](https://github.com/ecomfe/echarts-gl/blob/master/README.md)
- [Releases](https://github.com/ecomfe/echarts-gl/releases)
---
Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ecomfe-echarts-gl