The Principal Dev – Masterclass for Tech Leads

The Principal Dev – Masterclass for Tech LeadsNov 27-28

Join

Vue ECharts

Vue ECharts

Vue.js component for Apache ECharts™.

npm version test coverage View demo 前往中文版

Still using Vue 2? Read v7 docs here →

Installation & usage

npm

npm install echarts vue-echarts

Example

Demo → 
<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 recommended

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.

A modal for generating ECharts import code. The left panel shows a chart configuration in JSON, while the right panel displays TypeScript import statements for ECharts charts and components.

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";

CDN

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

Demo → 
<script src="https://cdn.jsdelivr.net/npm/echarts@6.0.0"></script>
<script src="https://cdn.jsdelivr.net/npm/vue@3.5.21"></script>
<script src="https://cdn.jsdelivr.net/npm/vue-echarts@8.0.1"></script>

const app = Vue.createApp(...)

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

See more examples here.

Props

Events

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

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

[!NOTE] Only the .once event modifier is supported as other modifiers are tightly coupled with the DOM event system.

Vue ECharts support the following events:

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>

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:

Composition API 
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);
Options API 
import { THEME_KEY } from 'vue-echarts'
import { computed } from 'vue'

export default {
  {
    provide: {
      [THEME_KEY]: 'dark'
    }
  }
}

// Or make injections reactive
export default {
  data() {
    return {
      theme: 'dark'
    }
  },
  provide() {
    return {
      [THEME_KEY]: computed(() => this.theme)
    }
  }
}

Methods

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

Slots new

Vue ECharts allows you to define ECharts option's tooltip.formatter and toolbox.feature.dataView.optionToContent callbacks via Vue slots instead of defining them in your option object. This simplifies custom HTMLElement rendering using familiar Vue templating.

Slot naming convention

Example mappings:

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

Usage 
<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>

Example →

[!NOTE] Slots take precedence over the corresponding callback defined in props.option.

Static methods

Static methods can be accessed from echarts itself.

CSP: style-src or style-src-elem

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:

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.

Join libs.tech

...and unlock some superpowers

GitHub

We won't share your data with anyone else.