Guide · Open source

How to use vue-echarts: install, render a chart and update it

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

vue-echarts is a Vue.js component for Apache ECharts, a charting library. You pass a chart configuration object to the component as a prop, and it creates and updates the chart for you. This guide shows you how to install it in a Vue 3 project, render a first chart, and use the props that control sizing, themes and updates.

Vue EChartsecomfe/vue-echarts · ★ 10.7k · MIT Install options & downloads

Quick start

1Check your project. Confirm you have a Vue 3 project and Node.js installed. Vue 2 projects should follow the v7 documentation.
2Install the packages. Run npm install echarts vue-echarts in your project folder.
3Import the ECharts parts you need. Import the renderer, chart type and components from echarts, then call use with them.
4Add the VChart component. Place VChart in your template and bind your configuration object to the option prop.
5Give the chart a height. Set a CSS height on the chart element so it has space to render.
6Update the data. Change the reactive option object and the chart updates to match.

Install vue-echarts and ECharts with npm

The package-manager route is npm. Install ECharts and vue-echarts together in your Vue 3 project. The README does not state a required Node.js version, so check the project's own requirements before you start.

Requires a Vue 3 project. Vue 2 users are pointed to the v7 documentation instead.

npm install echarts vue-echarts

Render your first chart with the VChart component

Import the ECharts modules you need, register them with ECharts' use function, then place the VChart component in your template and pass your configuration to its option prop. The example below draws a pie chart. Give the component a height in CSS, otherwise the container may have no size to draw into.

The README example also uses provide with THEME_KEY to set the theme to "dark". Set a class on the chart and style its height in a scoped style block.

<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: 1548, name: "Search Engines" }] }],
});
</script>

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

Import only the ECharts parts you use

The README recommends importing only the components and charts you need to keep your bundle small. You can paste your option object into the import code generator on the project site, and it outputs the matching import statements.

If you prefer simplicity over bundle size, you can import the whole ECharts bundle with a single line.

Recommended: import only needed charts and components, as shown in the example above.
Simple option: import "echarts" to load the full bundle.

import "echarts";

Load vue-echarts from a CDN without a build step

If you do not use a build tool, you can add the scripts to your HTML file and access the component through window.VueECharts. The README loads ECharts, Vue and vue-echarts from jsDelivr in this order. Register the component globally with app.component.

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

Understand the main props: option, theme, autoresize and init-options

option is the ECharts configuration object. Changing it makes vue-echarts compute an update and call setOption. theme accepts a string or object, and an empty string uses ECharts' default theme. init-options passes options to echarts.init. autoresize is false by default; set it to true to resize the chart when its container changes size.

When option changes, the component tries to keep existing chart models. It may rebuild the chart when needed, which can reset interaction state such as legend selections and data zoom. Keep any state that must survive a rebuild inside option.

option: the ECharts configuration; reactive changes trigger updates.
theme: a theme string or object; pass "" to use the default theme.
init-options: passed to echarts.init.
autoresize: boolean or an object with throttle (milliseconds) and onResize.
group: sets the chart connection group name.
Server-side rendering: the server renders only the container; the chart is drawn in the browser after mount.

What people use it for

Show a pie chart of traffic sources in a Vue 3 dashboard, as in the README example.
Add interactive charts to a Vue 3 app while keeping the ECharts configuration format.
Load charts in a plain HTML page through a CDN, without a build step.
Migrate a team that already uses Apache ECharts to a Vue-native wrapper.

Frequently asked questions

Is vue-echarts free to use?

vue-echarts is released under the MIT licence, according to the project's listing. Check the LICENSE file in the repository for the full terms.

Does vue-echarts work with Vue 2?

The README says Vue 2 users should read the v7 documentation. The main documentation covers the current Vue 3 setup.

Can vue-echarts render charts on the server?

No, not in the sense of producing a finished chart on the server. The server renders only the chart container, and ECharts initializes in the browser after the component mounts.

How do I install vue-echarts?

Run npm install echarts vue-echarts. ECharts is installed alongside it because the component uses Apache ECharts under the hood.

How does vue-echarts compare with vue-chartjs or ApexCharts?

vue-echarts wraps Apache ECharts, so you use ECharts' option format. vue-chartjs wraps Chart.js and vue3-apexcharts wraps ApexCharts, so choose based on which underlying library you prefer.

Why does my chart not appear or stay blank?

The README notes that the chart needs a container with a size, so set a height in CSS on the element. For resizing, enable autoresize, which is false by default.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

vue-echarts suits Vue 3 developers and teams who already use or want Apache ECharts and need a Vue-native wrapper. Projects on Vue 2, server-only rendering, or a charting library other than ECharts should look at the v7 docs, server-side tools, or one of the comparable libraries listed.

Install options & downloads