vue-echarts README

The project's README from github.com/ecomfe/vue-echarts. As one markdown file: README.md.

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

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.

Demo → 
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>

const app = Vue.createApp(...)

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

See more examples here.

Props

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:

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.

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

Static value:

import { THEME_KEY } from "vue-echarts";

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

Reactive value:

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

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

Properties

Methods

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:

Slots

Vue ECharts supports three slot categories:

Callback slot naming convention (tooltip* / dataView*)

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

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. 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 new

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

Available components:

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

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.

vue-echarts (ecomfe/vue-echarts)

Searching Database…

10.7K ·GitHub
Vue-echarts
Что это?Это компонент-обёртка для Vue.js (VChart), который позволяет декларативно выводить графики Apache ECharts внутри приложения на Vue. Он сам берёт на себя монтирование, изменение размера, темы и реактивное обновление настроек.
Это полноценная библиотека для графиков или тонкая обёртка для Vue над ECharts?Это тонкий слой компонентов Vue поверх самой Apache ECharts. Отрисовку графиков выполняет ECharts, а vue-echarts лишь предоставляет его как компонент Vue с пропсами, событиями и удобными для Vue API, например темизацией через provide/inject.
Как добавить это в проект на Vue?Установите пакет из npm, затем зарегистрируйте VChart глобально или локально как компонент либо используйте сборку из CDN и зарегистрируйте её в экземпляре приложения Vue.
Работает ли это с Vue 2 или только с Vue 3?Текущая версия рассчитана на Vue 3. Если вы всё ещё используете Vue 2, нужен более старый релиз v7 и его отдельная документация.
Обрабатывает ли это серверный рендеринг автоматически?Не полностью. При SSR на сервере отрисовывается только пустой контейнер графика, а сам экземпляр ECharts инициализируется лишь после монтирования компонента в браузере, поэтому настоящего серверного вывода графика нет.
Зачем мне заморачиваться с импортом по требованию, а не импортировать всё подряд?Импорт всего бандла ECharts прост, но раздувает JS. Проект рекомендует вручную импортировать только те типы графиков и компоненты, которые вы реально используете, и предоставляет онлайн-генератор кода, который выдаёт готовые инструкции import.
Как настроить тему графиков, например переключиться на тёмный режим?Передайте значение THEMEKEY через provide/inject API Vue. Это может быть обычная строка, ref или даже функция-геттер. VChart подхватит его и реактивно применит тему ECharts при её изменении.
Нужно ли подключать CSS вручную?Нет, на обычной веб-странице vue-echarts сам добавляет базовые стили в документ. Импортировать vue-echarts/style.css самостоятельно нужно только при отрисовке внутри shadow root или в другом контексте документа.
What are similar projects?element-plus, visx, echarts, naive-ui, Vela, shaders, mint-ui, primevue
Which topics is it in?echarts, vue-components, charting-library, component, chart, vue3, ssr, theme, visualization, component-library, data-visualization, vue
Creator
ecomfe
Size
30.4 MB
Stars
10.7K
Updated
CommitOct 16Releasev8.3.2Oct 09
Age
10y
Commits · 90 Days