zrender: the 2D drawing layer under Apache ECharts
A lightweight graphic library providing 2d draw for Apache ECharts
At a glance
- What is it?
- ZRender is a TypeScript 2D graphics library that Apache ECharts renders through. It suits teams that need imperative canvas or SVG drawing without a scene-graph framework, and it is a poor fit for anyone wanting declarative charting or the DOM to do the layout.
- Who is it for?
- Adopt zrender if you need an imperative 2D scene graph that can switch between canvas and SVG, or if you are extending ECharts at the shape level; skip it if you want declarative chart configuration, since that is ECharts' job, not this library's. Before committing, check the two things the README leaves open: how the SVG renderer behaves with the number of elements you plan to draw, and whether the BSD-3-Clause notice requirements fit your distribution model.
- Can I use it commercially?
- Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 25 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 29, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What ZRender is for, and who ends up using it
ZRender draws 2D graphics. The README describes it as "a lightweight graphic library which provides 2d draw for Apache ECharts", which is the clearest statement of both its purpose and its audience. ECharts is the consumer; if you are writing ECharts option objects, you are using ZRender indirectly and will rarely touch its API. The direct audience is narrower: developers who need shapes, paths, groups and hit testing on a canvas or an SVG element, and who do not want a full charting layer on top.
The topics list on the repository is candid about scope: 2d, canvas, html5, svg, vector-graphics. There is no data model, no scales, no axes, no legend. Those live in ECharts. ZRender gives you the drawing primitives and the event plumbing, and stops there. That boundary is the reason the library can stay small, and it is also the reason a team expecting a charting toolkit will be disappointed.
How the drawing pipeline is put together
The repository layout shows the shape of the architecture. src/ holds the TypeScript sources, dist/ holds the bundled build, and index.ts, index.js and index.d.ts sit at the top level as the entry points. The package.json points types at index.d.ts, module at index.js and main at dist/zrender.js, so a bundler that understands ES modules and a plain CommonJS consumer take different files.
The renderer split is visible in the sideEffects array of package.json, which names lib/canvas/canvas.js, lib/svg/svg.js and lib/all.js. Those are the two rendering backends plus the aggregate entry. An application initialises a ZRender instance against a DOM container and chooses a renderer at that point; the same scene description can be drawn through canvas or through SVG. That is the mechanism worth understanding: the scene graph is renderer-independent, and canvas versus SVG is a runtime decision rather than a rewrite.
The build pipeline is conventional TypeScript plus Rollup. build:bundle runs node build/build.js, build:lib runs tsc with -m ES2015 into lib/ and then node build/processLib.js, and the release script adds --minify before rebuilding the library. test runs Jest through test/ut/jest.config.js, lint runs ESLint over src/**/*.ts, and checktype runs tsc --noEmit. The only runtime dependency is tslib at 2.3.0, which is a small thing to carry.
Installing zrender from npm and drawing a first shape
The library is published on npm under the name zrender, and the README links the npm package badge and the documentation site at ecomfe.github.io/zrender-doc/public/. The install step follows from the package name:
npm install zrenderThat pulls in tslib as the single runtime dependency. The package exposes ES module and CommonJS entry points, so both a modern bundler and a Node-style require resolve without extra configuration.
The README does not include a usage example. It points to the documentation site for API detail, and that is where the constructor names, the renderer option and the shape classes are documented. Nothing in the repository README shows how an instance is created or how a shape is added, so the first real use has to be copied from the documentation site rather than from this page. What the repository does tell you is the entry surface: index.ts, index.js and index.d.ts at the top level, with types resolved through index.d.ts. After an instance is created against a container element, it owns a canvas or SVG element inside that container, and nothing is drawn until shapes are added to the scene. The renderer choice is made at initialisation, and the documentation describes the available renderer names. If you are extending ECharts rather than building standalone, the same primitives are reachable through ECharts' extension points, and the ECharts documentation is the better starting point for that path.
Where ZRender stops being the right tool
The most common mistake is adopting ZRender for something that is really a chart. There is no scale, no axis, no series, no tooltip and no data binding in this library. Rebuilding those on top of shapes is possible, and ECharts is the evidence that it can be done well, but it is a large amount of work that ECharts has already done. If your output is a chart, use ECharts.
The second boundary is interactivity model. ZRender gives you shapes and events, and the related searches suggest people look for "zrender events" specifically, but the README documents none of this. Event handling, hit testing and z-level ordering are documented on the documentation site rather than in the repository README, and the README does not describe them at all. Anyone evaluating the library from the GitHub page alone will find almost no API detail there.
The third boundary is the SVG path. SVG is a DOM tree, so a scene with a very large number of elements becomes a very large DOM tree, with the memory and layout costs that implies. Canvas has the opposite profile: one element, but no free accessibility or text selection. The library lets you pick, and it does not hide the consequences of the pick. The README does not document performance characteristics for either renderer, so that comparison has to come from your own measurements.
ZRender against Konva and plain canvas
Konva is the closest widely used alternative in the same space: a 2D scene graph for the browser with shapes, groups, layers and events. The practical difference is the renderer model. Konva's scene graph is built around its own layer and node hierarchy and its own event system, while ZRender's distinguishing feature is that the same scene can be drawn through canvas or through SVG, which the sideEffects entries in package.json make concrete. If you need to switch backends, or if you are already inside the ECharts ecosystem, ZRender is the shorter path. If you want a broader set of built-in shapes and a larger standalone community outside ECharts, Konva is the more obvious default.
The other alternative is not a library at all. The Canvas 2D API is right there in the browser, and for a static drawing or a small number of shapes it is less code than learning a scene graph. What you give up is everything ZRender provides on top: retained shapes you can move and restyle without redrawing the world, grouping, and the abstraction that lets the same description render to SVG. The decision is whether you are managing a scene or painting a picture.
Maintenance, releases and the BSD-3-Clause terms
The repository is not archived, and the last push to master was on 2026-09-06, which is recent enough that the project is clearly still receiving commits. Recent releases are 6.1.0 on 2026-05-04, 6.0.0 on 2025-07-23, and the 6.0.0-rc.1 prerelease on 2025-06-25. The gap between 6.0.0 and 6.1.0 is roughly nine months, so the major version is not churning; a team pinning to 6.x is not signing up for constant migration work. The README does not document a deprecation policy or a supported-versions window, so upgrade cost has to be judged from the changelog and the release notes rather than from a stated promise.
The licence is BSD-3-Clause, and the README reproduces the full text with copyright held by Baidu Inc. from 2017. The three clauses are the standard ones: retain the copyright notice and conditions in source redistributions, reproduce them in binary redistributions, and do not use the copyright holder's or contributors' names to endorse derived products without permission. The README also carries a notice that Apache ECharts, Apache, the Apache feather and the ECharts logo are trademarks of the Apache Software Foundation, which matters if you are redistributing something that references ECharts branding. This is a description of the licence text, not legal advice; check the terms against your own distribution model.
Editorial conclusion
Adopt zrender if you need an imperative 2D scene graph that can switch between canvas and SVG, or if you are extending ECharts at the shape level; skip it if you want declarative chart configuration, since that is ECharts' job, not this library's. Before committing, check the two things the README leaves open: how the SVG renderer behaves with the number of elements you plan to draw, and whether the BSD-3-Clause notice requirements fit your distribution model. The last push to master was on 2026-09-06, so the repository is live, but that tells you nothing about your own rendering budget.
Frequently asked questions
What is zrender in relation to ECharts?
ZRender is the 2D drawing library that Apache ECharts renders through. The README describes it as "a lightweight graphic library which provides 2d draw for Apache ECharts", so ECharts handles charts and configuration while ZRender handles shapes and rendering.
How do I install zrender?
It is published on npm as zrender, and tslib at 2.3.0 is the only runtime dependency. The package exposes an ES module entry and a CommonJS bundle, so bundlers and require both resolve.
Can zrender render to SVG instead of canvas?
Yes. The sideEffects array in package.json lists lib/canvas/canvas.js and lib/svg/svg.js as separate entries, and the renderer is chosen when a ZRender instance is initialised. The same scene description can therefore be drawn through either backend.
What licence does zrender use?
BSD-3-Clause, with copyright held by Baidu Inc. from 2017. The README reproduces the full text, which requires retaining the copyright notice in source and binary redistributions and restricts use of the copyright holder's name for endorsement.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/ecomfe-zrender)