vue-echarts 8.3.0: A Vue 3 Wrapper for Apache ECharts, and What It Does Not Do

The glue code vue-echarts removes

Apache ECharts is a canvas charting library that knows nothing about Vue. Wiring it into a component means calling echarts.init on a ref, watching your option object, calling setOption, listening for resize, and calling dispose on unmount. Every one of those steps is a place to leak an instance or leave a stale chart on screen.

vue-echarts is a Vue 3 component that performs that lifecycle for you. The README describes it plainly as a "Vue.js component for Apache ECharts™". The intended audience is a Vue 3 application that already has ECharts option objects, or plans to build them, and wants them rendered declaratively rather than imperatively. If you are not on Vue 3, the README points Vue 2 users at the v7 docs on the 7.x branch, which is a different API surface and a different install target.

How the option prop turns into setOption calls

The component takes an option prop, described in the README as ECharts' "universal interface". Modifying that prop triggers vue-echarts to compute an update plan and call setOption. The plan is the part worth understanding, because it is not a pass-through.

The README states that reactive updates describe the complete configuration, and that vue-echarts preserves existing models where merging can apply that configuration, rebuilding when necessary to remove stale settings. In other words, it tries to merge, and falls back to a rebuild. A rebuild can reset interaction state such as legend selections and data zoom. That is a real behavioural difference from calling setOption yourself with the same arguments every time, and it is why the README advises keeping state that must survive a rebuild in option.

Two escape hatches exist. If you supply update-options, either as a prop or through injection, vue-echarts forwards it directly to setOption and skips the planner entirely. After you remove it, the first smart source-option update rebuilds once to establish a safe structural baseline. Separately, a failed option or theme submission invalidates that baseline, so the next smart update rebuilds rather than trusting a possibly partial update. Automatic option, theme and slot changes are batched after Vue updates; clear() takes effect immediately and cancels already queued automatic work.

Install and render a first chart

The README's npm instructions install two packages, not one: the wrapper and ECharts itself.

npm install echarts vue-echarts

The README recommends on-demand importing to keep the bundle small, so a minimal working component imports the renderer, the chart type and the components it actually uses, then registers them with ECharts' use(). The example below is the README's pie chart with the title, tooltip and legend components registered. The chart element needs an explicit height; the README's scoped style sets 400px.

<template>
  <VChart class="chart" :option="option" />
</template>

<script setup>
import { use } from "echarts/core";
import { CanvasRenderer } from "echarts/renderers";
import { PieChart } from "echarts/charts";
import { TitleComponent, TooltipComponent, LegendComponent } from "echarts/components";
import VChart, { THEME_KEY } from "vue-echarts";
import { ref, provide } from "vue";

use([CanvasRenderer, PieChart, TitleComponent, TooltipComponent, LegendComponent]);

provide(THEME_KEY, "dark");

const option = ref({
  title: { text: "Traffic Sources", left: "center" },
  series: [{ name: "Traffic Sources", type: "pie", radius: "55%", data: [
    { value: 335, name: "Direct" },
    { value: 310, name: "Email" },
  ] }],
});
</script>

<style scoped>
.chart {
  height: 400px;
}
</style>

Forgetting the use() call is the most common failure here: the component mounts, the container appears, and nothing is drawn because the chart type was never registered. If you would rather skip that bookkeeping, the README offers the blunt alternative of importing the whole bundle.

import "echarts";

The README also documents a code generator at vue-echarts.dev/#codegen: paste your option code in, and it emits the exact import statements. That is a better fit than memorising which component belongs to which chart.

Themes, injection keys and a rebuild you did not ask for

Theme is a prop, and it can also be injected under THEME_KEY, which is how the example above sets a dark theme for a subtree. Passing an empty string is documented as a way to use ECharts' default theme while overriding an injected one.

The cost of changing themes is stated in the README: ECharts recreates its model when changing themes, and vue-echarts reapplies the latest automatic option, but uncontrolled interaction state such as legend selection or data zoom may reset. A user who has toggled series off in the legend and then flips your light/dark switch can lose that selection. The documented fix is to keep that state in option, which means lifting it out of ECharts and into your Vue state. That is a design decision you inherit, not a bug.

The same warning applies to the smart update path generally: a rebuild can reset interaction state. If your application treats legend selection or zoom as meaningful user input, plan for it before you ship a theme toggle.

SSR renders the container, not the chart

This is the limitation most likely to disqualify vue-echarts for a given project. The README states that VChart can be rendered and hydrated by Vue SSR frameworks, but that the server renders only the chart container; ECharts initializes after the component mounts in the browser. It then closes the door explicitly: the low-level ECharts ssr field in init-options does not enable server-side chart rendering in VChart.

So if you need chart pixels in the initial HTML payload, for a report export, an email, or a crawler that does not run JavaScript, this component is the wrong layer. You would generate the image with ECharts' own server-side rendering outside Vue and serve that. For a normal dashboard where the chart appears after hydration, the container-only behaviour is fine and the README's framing is honest about it.

The styling story has a similar boundary. When imported in a browser, vue-echarts injects its base styles into the global document, so no CSS import is normally required. Inside a shadow root or another document, you must include vue-echarts/style.css in that styling scope, and the README points to a CSP section for the fallback older browsers need. Under a strict style-src policy, that global injection is the thing to check first.

Nuxt, and how it differs from the React binding

People searching for Nuxt ECharts are looking for the same problem in a different framework. There is no separate Nuxt package in this repository; the SSR section above is the relevant answer, and Nuxt's client-only rendering is the usual way to satisfy it. The README does not document a Nuxt module, so treat any integration as ordinary Vue component usage.

The closer comparison is ECharts React, which occupies the same niche for React. The difference is not the chart library, since both wrap the same ECharts, but the update model. vue-echarts documents a planner that merges when it can and rebuilds when it must, plus an update-options escape hatch that bypasses the planner. That is a specific, documented contract you can reason about. If you are choosing between frameworks rather than chart wrappers, the binding is not the deciding factor; the option object you already have is portable across both.

Licence, releases and what maintenance looks like here

The package is MIT licensed, and package.json declares "license": "MIT" with the author listed as GU Yiling. MIT is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and permission notice travel with it. That is the licence text, not legal advice; if your organisation has a policy on attribution in bundled dependencies, read LICENSE rather than a summary.

On cadence, the last push to the repository was on 2026-09-15, and the most recent release listed is v8.3.0 on 2026-09-06, following v8.2.0 on 2026-08-30 and v8.1.0 on 2026-08-07. The repository is not archived. Three minor releases in roughly six weeks is a fast enough pace that you should pin a version and read CHANGELOG.md before bumping, particularly if you depend on the smart update behaviour described above. The repository ships a benchmarks/ directory and a bench:graphic script, but the README does not publish results from them, so do not read performance numbers into their presence.

Editorial conclusion

Adopt vue-echarts if you are on Vue 3 and want a single <VChart> component to own ECharts init, resize and disposal instead of writing that glue yourself. Do not adopt it if you need server-rendered chart markup, or if you expect the Vue 2 API: v7 is a separate branch with separate docs. Before committing, verify two things in your own option objects: whether any interaction state you rely on (legend selection, data zoom) lives outside option and would be lost on a theme change, and whether your bundle can tolerate the on-demand import list the codegen tool produces.

Frequently asked questions

Official sources

1. ecomfe/vue-echarts on GitHub
2. License: MIT
3. Project website
4. README
5. Releases