Vue ECharts

Vue.js component for Apache ECharts™.

Still using Vue 2? Read v7 docs here →

Installation & usage

npm

npm install echarts vue-echarts

Example

<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",
  },
  tooltip: {
    trigger: "item",
    formatter: "{a} <br/>{b} : {c} ({d}%)",
  },
  legend: {
    orient: "vertical",
    left: "left",
    data: ["Direct", "Email", "Ad Networks", "Video Ads", "Search Engines"],
  },
  series: [
    {
      name: "Traffic Sources",
      type: "pie",
      radius: "55%",
      center: ["50%", "60%"],
      data: [
        { value: 335, name: "Direct" },
        { value: 310, name: "Email" },
        { value: 234, name: "Ad Networks" },
        { value: 135, name: "Video Ads" },
        { value: 1548, name: "Search Engines" },
      ],
      emphasis: {
        itemStyle: {
          shadowBlur: 10,
          shadowOffsetX: 0,
          shadowColor: "rgba(0, 0, 0, 0.5)",
        },
      },
    },
  ],
});
</script>

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

On-demand importing 

To keep your bundle size small, we recommend manually importing the components and charts you need from ECharts. To make this easier, we’ve created an import code generator. Simply paste your option code into the tool, and it will generate the exact import statements for you.

Try it →

But if you really want to import the whole ECharts bundle without having to import modules manually, just add this in your code:

import "echarts";

Styles

When Vue ECharts is imported in a browser, it injects its base styles into the global document, so no CSS import is normally required. For a shadow root or another document, include vue-echarts/style.css in that styling scope; see CSP for the fallback required by older browsers.

Server-side rendering

VChart can be rendered and hydrated by Vue SSR frameworks. The server renders only the chart container; ECharts initializes after the component mounts in the browser. The low-level ECharts ssr field in init-options does not enable server-side chart rendering in VChart.

CDN

Drop <script> inside your HTML file and access the component via window.VueECharts.

<script src="https://cdn.jsdelivr.net/npm/echarts@6.1.0"></script>
<script src="https://cdn.jsdelivr.net/npm/vue@3.5.41"></script>
<script src="https://cdn.jsdelivr.net/npm/vue-echarts@8.3.0"></script>

const app = Vue.createApp(...)

// register globally (or you can do it locally)
app.component('VChart', VueECharts)

See more examples here.

Props

• init-options: object

  Optional chart init configurations. See echarts.init‘s opts parameter here →

  Injection key: INIT_OPTIONS_KEY.

• theme: string | object

  Theme to be applied. See echarts.init‘s theme parameter here →

  Pass an empty string to use ECharts’ default theme while overriding an injected theme.

  ECharts recreates its model when changing themes. Vue ECharts reapplies the latest automatic option, but uncontrolled interaction state (such as legend selection or data zoom) may reset. Keep state that must survive a rebuild in option.

  Injection key: THEME_KEY.

• option: object

  ECharts’ universal interface. Modifying this prop triggers Vue ECharts to compute an update plan and call setOption. Read more here → Temporarily removing the prop pauses automatic updates without letting a later theme change roll the chart back to its initial option.

  Smart update

  Reactive updates describe the complete configuration. Vue ECharts preserves existing models where merging can apply that configuration, and rebuilds when necessary to remove stale settings. A rebuild can reset interaction state such as legend selections and data zoom.

  • If you supply update-options (via prop or injection), Vue ECharts forwards it directly to setOption and skips the planner. After you remove it, the first smart source-option update rebuilds once to establish a safe structural baseline.
  • A failed option or theme submission invalidates that baseline. The next smart update rebuilds instead of trusting a potentially partial update.
  • Automatic option, theme, and slot changes are batched after Vue updates. clear() takes effect immediately and cancels already queued automatic work; later changes can populate the chart again.
  • Manual setOption calls (only available when manual-update is true) behave like native ECharts, honouring only the per-call override you pass in and are not carried across re-initializations.
  • Updates containing a graphic element $action keep normal merge for graphic so the command can target the existing element tree; safe removals of unrelated components still use replaceMerge. Changes requiring a full rebuild cannot be applied together with these commands. For complete snapshot semantics, describe the resulting graphic tree without $action commands.
  • Otherwise, Vue ECharts analyses the change: component removals, reordering, and deletions inside anonymous components use replaceMerge when it can reproduce the requested order; deletions inside ID-matched components, identity ordering that replaceMerge cannot reproduce, newly introduced or shrinking non-component arrays, first-time ARIA configuration, and other risky changes fall back to notMerge: true.

• update-options: object

  Options for updating chart option. If supplied (or injected), Vue ECharts forwards it directly to setOption, skipping the smart update. See echartsInstance.setOption‘s opts parameter here →

  Injection key: UPDATE_OPTIONS_KEY.

• group: string

  Group name to be used in chart connection. See echartsInstance.group here →

• autoresize: boolean | { throttle?: number, onResize?: () => void } (default: false)

  Whether to resize the chart automatically when its rendering container changes size. Use the options object to specify a custom throttle delay (in milliseconds) and/or an extra resize callback function. Zero-sized containers are not resized; the configured throttle also applies when they recover.

• loading: boolean (default: false)

  Whether the chart is in loading state.

• loading-type: string

  Name of the registered loading effect. It is passed as the first argument to echartsInstance.showLoading; omit it to use the default effect.

• loading-options: object

  Configuration item of loading animation. Default-effect fields are typed explicitly, and additional fields for custom effects are forwarded to echartsInstance.showLoading. See its opts parameter here →

  Injection key: LOADING_OPTIONS_KEY.

• manual-update: boolean (default: false)

  Handy for performance-sensitive charts (large or high-frequency updates). When set to true, Vue uses the option prop for the initial render but does not deeply observe it afterwards; later prop changes do nothing and you must drive updates via setOption on a template ref. The component-managed initial render still honors update-options, while later manual calls use only their per-call arguments. If autoresize defers that first render and you successfully call setOption first, the manual call takes precedence. If the chart re-initializes (for example due to init-options changes, flipping manual-update, or a remount), the manual state is discarded and the chart is rendered again from the current option value.

TypeScript

Component-specific prop types are available from the package root:

import type { AutoResize, LoadingOptions } from "vue-echarts";

For a typed template ref:

import VChart from "vue-echarts";
import { ref } from "vue";

const chart = ref<InstanceType<typeof VChart> | null>(null);

Vue 3.5’s useTemplateRef can infer this type automatically.

Events

You can bind events with Vue’s v-on directive.

<template>
  <VChart :option="option" @highlight="handleHighlight" />
</template>

[!NOTE] ECharts and ZRender events only support the .once modifier; other modifiers are specific to DOM events. Listeners using the native: prefix support Vue’s normal DOM event modifiers.

Vue ECharts supports the following events:

• highlight →
• downplay →
• selectchanged →
• legendselectchanged →
• legendselected →
• legendunselected →
• legendselectall →
• legendinverseselect →
• legendscroll →
• datazoom →
• datarangeselected →
• graphroam →
• georoam →
• treeroam →
• sankeyroam →
• focusnodeadjacency, unfocusnodeadjacency (legacy graph adjacency focus actions)
• dragnode →
• treeexpandandcollapse →
• timelinechanged →
• timelineplaychanged →
• restore →
• dataviewchanged →
• magictypechanged →
• geoselectchanged →
• geoselected →
• geounselected →
• axisbreakchanged →
• axisareaselected →
• brush →
• brushend →
• brushselected →
• showtip →
• hidetip →
• updateaxispointer →
• globalcursortaken →
• updated (after an ECharts update completes)
• rendered →
• finished →
• Mouse events
  • click →
  • dblclick →
  • mouseover →
  • mouseout →
  • mousemove →
  • mousedown →
  • mouseup →
  • globalout →
  • contextmenu →
• ZRender events
  • zr:click
  • zr:dblclick
  • zr:mouseout
  • zr:mouseover
  • zr:mouseup
  • zr:mousedown
  • zr:mousemove
  • zr:contextmenu
  • zr:globalout
  • zr:mousewheel
  • zr:drag
  • zr:dragstart
  • zr:dragend
  • zr:dragenter
  • zr:dragleave
  • zr:dragover
  • zr:drop

See supported events in the ECharts API reference →

Native DOM events

As Vue ECharts binds events to the ECharts instance by default, there is some caveat when using native DOM events. You need to prefix the event name with native: to bind native DOM events.

<template>
  <VChart @native:click="handleClick" />
</template>

Case-sensitive custom events are supported by writing their exact name after native:, for example @native:ChartReady.

Event handlers passed via attrs are reactive by default. Updates to onClick, onZr:*, or onNative:* handlers take effect automatically. Multiword handlers accept idiomatic camel case, such as onDataZoom, onBrushEnd, and onZr:mouseMove; existing forms such as onDatazoom, onBrushend, and onZr:mousemove remain supported.

Provide / inject

Vue ECharts provides provide/inject API for theme, init-options, update-options and loading-options to help configuring contextual options. eg. for theme you can use the provide API like this:

Explicit props take precedence over injected values. Reactive providers may resolve to null or undefined while a contextual value is unavailable.

import { THEME_KEY } from "vue-echarts";
import { provide } from "vue";

provide(THEME_KEY, "dark");

// or provide a ref
const theme = ref("dark");
provide(THEME_KEY, theme);

// getter is also supported
provide(THEME_KEY, () => theme.value);

import { THEME_KEY } from "vue-echarts";

export default {
  provide: {
    [THEME_KEY]: "dark",
  },
};

import { THEME_KEY } from "vue-echarts";
import { computed } from "vue";

export default {
  data() {
    return {
      theme: "dark",
    };
  },
  provide() {
    return {
      [THEME_KEY]: computed(() => this.theme),
    };
  },
};

Properties

• chart: ECharts | undefined

  The current underlying ECharts instance. This property is read-only and changes when the component re-initializes the chart; it becomes undefined after disposal. Prefer the methods below for supported operations. Direct option mutations are not tracked by the smart updater, so use manual-update when driving setOption imperatively.

• root: HTMLElement | undefined

  The component’s read-only <x-vue-echarts> root element, available after mounting.

Methods

• setOption →
• getWidth →
• getHeight →
• getDom →
• getZr →
• getId →
• getOption →
• isSSR →
• getDevicePixelRatio →
• resize →
• makeActionFromEvent →
• dispatchAction →
• updateLabelLayout →
• convertToPixel →
• convertToLayout →
• convertFromPixel →
• containPixel →
• getVisual →
• renderToCanvas →
• renderToSVGString →
• getSvgDataURL →
• getDataURL →
• getConnectedDataURL →
• appendData →
• clear →
• isDisposed →
• dispose →

dispose is terminal for the current component instance. Use it instead of calling dispose on the raw chart instance; remount the component to initialize a new chart.

[!NOTE] The following ECharts instance methods aren’t exposed because their functionality is already provided by component props:

• showLoading / hideLoading: use the loading, loading-type and loading-options props instead.
• setTheme: use the theme prop instead.

Slots

Vue ECharts supports three slot categories:

• Callback slots for tooltip.formatter.
• Callback slots for toolbox.feature.dataView.optionToContent.
• Optional #graphic slot (enabled by importing vue-echarts/graphic) for building option.graphic declaratively with G* components.

Callback slot naming convention (tooltip* / dataView*)

These naming rules apply to callback slots only. The graphic slot name is always #graphic.

• Slot names begin with tooltip/dataView, followed by hyphen-separated path segments to the target.
• If tooltip or toolbox is an array, place its numeric component index immediately after the slot prefix; any remaining segments still locate the owning option.
• Each non-empty segment corresponds to an option property name or an array index (for arrays, use the numeric index).
• Array segments are patched only when the corresponding array entries already exist; callback slots do not create missing component or data arrays.
• The reserved JavaScript path segment __proto__ is rejected.
• The constructed slot name maps directly to the nested callback it overrides.

Example mappings:

• tooltip → option.tooltip.formatter
• tooltip-0 → option.tooltip[0].formatter
• tooltip-baseOption → option.baseOption.tooltip.formatter
• tooltip-xAxis-1 → option.xAxis[1].tooltip.formatter
• tooltip-series-2-data-4 → option.series[2].data[4].tooltip.formatter
• dataView → option.toolbox.feature.dataView.optionToContent
• dataView-1 → option.toolbox[1].feature.dataView.optionToContent
• dataView-media-1-option → option.media[1].option.toolbox.feature.dataView.optionToContent

The slot props correspond to the first parameter of the callback function.

<template>
  <VChart :option="chartOptions">
    <!-- Global `tooltip.formatter` -->
    <template #tooltip="params">
      <div v-for="(param, i) in params" :key="i">
        <span v-html="param.marker" />
        <span>{{ param.seriesName }}</span>
        <span>{{ param.value[0] }}</span>
      </div>
    </template>

    <!-- Tooltip on xAxis -->
    <template #tooltip-xAxis="params">
      <div>X-Axis : {{ params.value }}</div>
    </template>

    <!-- Data View Content -->
    <template #dataView="option">
      <table>
        <thead>
          <tr>
            <th v-for="(t, i) in option.dataset[0].source[0]" :key="i">
              {{ t }}
            </th>
          </tr>
        </thead>
        <tbody>
          <tr v-for="(row, i) in option.dataset[0].source.slice(1)" :key="i">
            <th>{{ row[0] }}</th>
            <td v-for="(v, i) in row.slice(1)" :key="i">{{ v }}</td>
          </tr>
        </tbody>
      </table>
    </template>
  </VChart>
</template>

[!NOTE] Slots take precedence over the corresponding callback defined in props.option. Removing a callback slot explicitly clears its injected function without rebuilding the chart. After adding or removing a callback slot in manual-update mode, call chartRef.setOption(...) to submit the latest slot set.

Graphic slot 

import { GGroup, GRect, GText } from "vue-echarts/graphic";

Available components:

• GGroup
• GRect
• GCircle
• GEllipse
• GText
• GLine
• GPolyline
• GPolygon
• GImage
• GSector
• GRing
• GArc
• GBezierCurve

Read more at ECharts option.graphic →

[!NOTE]

• Graphic element events additionally support dblclick and contextmenu.
• Event listeners support the .once modifier.
• Returning true from a graphic element listener stops the event from bubbling.
• Path components accept auto-batch to opt into ZRender’s Canvas path batching.
• The option prop may be omitted for graphic-only charts.
• #graphic overrides option.graphic. In manual-update mode, call chartRef.setOption(...) to apply changes.
• Wrapper components and Fragments preserve their rendered graphic order. Compatible property changes update only changed elements, preserving unchanged elements and their running animations. Removing fields, changing types, or changing tree structure rebuilds the graphic component.
• Graphic-only changes omit unrelated source options when safe. Explicit notMerge or replaceMerge targeting other components still submits the full source option.

<script setup lang="ts">
import { ref } from "vue";
import type { ElementEvent } from "echarts/core";

const option = {
  xAxis: { type: "category", data: ["Mon", "Tue", "Wed"] },
  yAxis: { type: "value" },
  series: [{ type: "line", data: [120, 200, 150] }],
};

const overlay = ref({ x: 84, y: 22 });

function onDrag(event: ElementEvent) {
  overlay.value.x = event.offsetX - 44;
  overlay.value.y = event.offsetY - 14;
}
</script>

<template>
  <VChart :option="option">
    <template #graphic>
      <GGroup id="drag-handle" :x="overlay.x" :y="overlay.y">
        <GRect :width="88" :height="28" :r="6" fill="#5470c6" draggable @drag="onDrag" />
        <GText
          :x="10"
          :y="8"
          :text="`x: ${Math.round(overlay.x)} y: ${Math.round(overlay.y)}`"
          fill="#fff"
        />
      </GGroup>
    </template>
  </VChart>
</template>

Static methods

Static methods can be accessed from echarts itself.

CSP: style-src or style-src-elem

Vue ECharts injects its base styles into the global document when its module is evaluated. Shadow roots and other documents do not receive these styles; include vue-echarts/style.css in each target styling scope when needed.

If you are both enforcing a strict CSP that prevents inline <style> injection and targeting browsers that don’t support the CSSStyleSheet() constructor, you need to manually include vue-echarts/style.css.

Migration to v8

[!NOTE] Please make sure to read the upgrade guide for ECharts 6 as well.

The following breaking changes are introduced in vue-echarts@8:

• Vue 2 support is dropped: If you still need to stay on Vue 2, use vue-echarts@7.

• Browser compatibility changes: We no longer provide compatibility for browsers without native class support. If you need to support legacy browsers, you must transpile the code to ES5 yourself.

• CSP entry point removed: The entry point vue-echarts/csp is removed. Use vue-echarts instead. You only need to manually include vue-echarts/style.css if you are both enforcing a strict CSP that prevents inline <style> injection and targeting browsers that don’t support the CSSStyleSheet() constructor.

Local development

pnpm i
pnpm dev

Open http://localhost:5173 to see the demo.

For testing and CI details, see tests/TESTING.md.

Notice

The Apache Software Foundation Apache ECharts, ECharts, Apache, the Apache feather, and the Apache ECharts project logo are either registered trademarks or trademarks of the Apache Software Foundation.