0
# Vue-ECharts
1

2
Vue-ECharts is a Vue.js component for Apache ECharts™, providing declarative data visualization with seamless integration for both Vue 2.7+ and Vue 3.1+. It offers reactive chart updates, comprehensive TypeScript support, automatic resizing, theme system, and CSP (Content Security Policy) compliance.
3

4
## Package Information
5

6
- **Package Name**: vue-echarts
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install echarts vue-echarts`
10
- **Vue Compatibility**: Vue 2.7+ and Vue 3.1+
11
- **Peer Dependencies**: echarts ^5.5.1, vue ^2.7.0 || ^3.1.1
12

13
## Core Imports
14

15
```typescript
16
import VChart from "vue-echarts";
17
import VChart, { THEME_KEY } from "vue-echarts";
18
```
19

20
For CSP-compliant builds (when `style-src` or `style-src-elem` CSP directives prevent inline styles):
21

22
```typescript
23
import VChart from "vue-echarts/csp";
24
import "vue-echarts/csp/style.css";
25
```
26

27
> **CSP Note**: The CSP build prevents inline `<style>` injection by extracting all styles to a separate CSS file. Use this when your application has strict Content Security Policy requirements.
28

29
CommonJS:
30

31
```javascript
32
const VChart = require("vue-echarts");
33
```
34

35
UMD (Browser):
36

37
```html
38
<script src="https://unpkg.com/vue-echarts/dist/index.min.js"></script>
39
<!-- Global: VueECharts -->
40
```
41

42
## Basic Usage
43

44
### Vue 3 with Composition API
45

46
```vue
47
<template>
48
  <v-chart class="chart" :option="option" />
49
</template>
50

51
<script setup>
52
import { use } from "echarts/core";
53
import { CanvasRenderer } from "echarts/renderers";
54
import { PieChart } from "echarts/charts";
55
import { TitleComponent, TooltipComponent } from "echarts/components";
56
import VChart, { THEME_KEY } from "vue-echarts";
57
import { ref, provide } from "vue";
58

59
use([CanvasRenderer, PieChart, TitleComponent, TooltipComponent]);
60

61
provide(THEME_KEY, "dark");
62

63
const option = ref({
64
  title: { text: "My Chart" },
65
  series: [{
66
    type: "pie",
67
    data: [
68
      { value: 335, name: "Direct" },
69
      { value: 310, name: "Email" }
70
    ]
71
  }]
72
});
73
</script>
74

75
<style scoped>
76
.chart { height: 400px; }
77
</style>
78
```
79

80
### Vue 2 Options API
81

82
```vue
83
<template>
84
  <v-chart class="chart" :option="option" />
85
</template>
86

87
<script>
88
import { use } from "echarts/core";
89
import { CanvasRenderer } from "echarts/renderers";
90
import { LineChart } from "echarts/charts";
91
import VChart from "vue-echarts";
92

93
use([CanvasRenderer, LineChart]);
94

95
export default {
96
  components: { VChart },
97
  data() {
98
    return {
99
      option: {
100
        xAxis: { type: "category", data: ["Mon", "Tue", "Wed"] },
101
        yAxis: { type: "value" },
102
        series: [{ data: [120, 200, 150], type: "line" }]
103
      }
104
    };
105
  }
106
};
107
</script>
108
```
109

110
## Architecture
111

112
Vue-ECharts is built around several key components:
113

114
- **Main Component**: Vue component that wraps ECharts instances with reactive props
115
- **Composables System**: Reusable composition functions for common patterns (API access, auto-resize, loading states)
116
- **Injection System**: Vue's provide/inject for theme and configuration inheritance
117
- **Dual Build System**: Standard and CSP-compliant builds for different security requirements
118
  - **Standard Build**: Default version with inline style injection
119
  - **CSP Build**: Content Security Policy compliant version with external CSS
120
- **Vue Compatibility Layer**: Support for both Vue 2.7+ and Vue 3.1+ via vue-demi
121

122
## Capabilities
123

124
### Main Component
125

126
The core Vue component that renders ECharts with reactive props and comprehensive event handling. Supports all ECharts configurations with Vue's reactivity system.
127

128
```typescript { .api }
129
declare const VChart: DefineComponent<
130
  ChartProps & ChartEventProps,
131
  {
132
    root: Ref<HTMLElement | undefined>;
133
    chart: Ref<EChartsType | undefined>;
134
  },
135
  {},
136
  {},
137
  ChartMethods
138
>;
139

140
interface ChartProps {
141
  /** ECharts option configuration object */
142
  option?: Option;
143
  /** Chart theme (object or string name) */
144
  theme?: Theme;
145
  /** ECharts initialization options */
146
  initOptions?: InitOptions;
147
  /** Chart update options */
148
  updateOptions?: UpdateOptions;
149
  /** Auto-resize configuration */
150
  autoresize?: AutoResize;
151
  /** Loading state */
152
  loading?: boolean;
153
  /** Loading animation options */
154
  loadingOptions?: LoadingOptions;
155
  /** Chart group name for linking charts */
156
  group?: string;
157
  /** Manual update mode */
158
  manualUpdate?: boolean;
159
}
160
```
161

162
[Main Component](./main-component.md)
163

164
### Injection System
165

166
Vue injection keys for providing themes and configuration options to child components.
167

168
```typescript { .api }
169
declare const THEME_KEY: InjectionKey<ThemeInjection>;
170
declare const INIT_OPTIONS_KEY: InjectionKey<InitOptionsInjection>;
171
declare const UPDATE_OPTIONS_KEY: InjectionKey<UpdateOptionsInjection>;
172
declare const LOADING_OPTIONS_KEY: InjectionKey<LoadingOptionsInjection>;
173
```
174

175
[Injection System](./injection-system.md)
176

177
## Core Types
178

179
```typescript { .api }
180
// Imported from ECharts core
181
import type { SetOptionOpts, ECElementEvent, ElementEvent } from "echarts/core";
182
import type { Ref, DefineComponent, InjectionKey } from "vue-demi";
183

184
/** ECharts instance type */
185
type EChartsType = ReturnType<typeof init>;
186

187
/** Chart option configuration */
188
type Option = Parameters<EChartsType["setOption"]>[0];
189

190
/** Chart theme */
191
type Theme = NonNullable<Parameters<typeof init>[1]>;
192

193
/** Auto-resize configuration */
194
type AutoResize = boolean | {
195
  throttle?: number;
196
  onResize?: () => void;
197
};
198

199
/** Loading animation options */
200
interface LoadingOptions {
201
  text?: string;
202
  textColor?: string;
203
  fontSize?: number | string;
204
  fontWeight?: number | string;
205
  fontStyle?: string;
206
  fontFamily?: string;
207
  maskColor?: string;
208
  showSpinner?: boolean;
209
  color?: string;
210
  spinnerRadius?: number;
211
  lineWidth?: number;
212
  zlevel?: number;
213
}
214

215
/** Chart initialization options */
216
type InitOptions = NonNullable<Parameters<typeof init>[2]>;
217

218
/** Chart update options */
219
type UpdateOptions = SetOptionOpts;
220

221
/** ECharts element event type */
222
type ECElementEvent = import("echarts/core").ECElementEvent;
223

224
/** ZRender element event type */
225
type ElementEvent = import("echarts/core").ElementEvent;
226

227
/** Generic injection type */
228
type Injection<T> = T | null | Ref<T | null> | { value: T | null };
229

230
/** Theme injection type */
231
type ThemeInjection = Injection<Theme>;
232

233
/** Init options injection type */
234
type InitOptionsInjection = Injection<InitOptions>;
235

236
/** Update options injection type */
237
type UpdateOptionsInjection = Injection<UpdateOptions>;
238

239
/** Loading options injection type */
240
type LoadingOptionsInjection = Injection<LoadingOptions>;
241
```