vue-echarts

Vue ECharts wraps Apache ECharts as a native Vue 3 component, letting developers drop a <VChart> element into their templates and drive it with a single reactive option prop. Instead of manually calling echarts.init, tracking resize events, and deciding when to merge versus replace chart configuration, the component manages the entire chart lifecycle — initialization, disposal, resizing, loading states, and theme application — behind Vue’s reactivity system.

Under the hood it includes a structural diffing engine that inspects successive option objects to decide whether ECharts should merge the new configuration or fully replace it, avoiding stale series, legends, or graphic elements left over from a previous render. It also supports declarative graphic-layer overlays via slots, group-linked charts, SSR-safe rendering, and a Web Component build for use outside Vue, making it the de facto way to use ECharts from a Vue codebase.

What You Get

• A VChart component with a reactive option prop instead of manual echarts.init/setOption calls
• A smart update planner that chooses merge vs. notMerge/replaceMerge per option change to avoid stale chart state
• Automatic container resize handling via an autoresize prop with optional throttling
• Theme injection (THEME_KEY) so a whole app can share one chart theme without repeating props
• A manual-update mode with a typed setOption method for performance-sensitive, high-frequency updates
• A declarative #graphic slot (via vue-echarts/graphic) for building ECharts graphic overlays without the imperative graphic API
• SSR-safe rendering and an auto-registered Web Component build for use outside Vue

Common Use Cases

• Building analytics dashboards and admin panels in Vue 3 without hand-writing ECharts lifecycle glue per widget
• Trimming bundle size with ECharts’ on-demand import codegen tool alongside VChart
• Sharing one chart theme app-wide by injecting THEME_KEY at the root instead of repeating a theme prop
• Driving high-frequency or streaming chart updates (e.g. live trading views) via manual-update and direct setOption calls on a template ref
• Adding annotated overlays (threshold lines, custom markers) with the reactive #graphic slot

Under The Hood

Architecture The component (src/ECharts.ts) is a single defineComponent built entirely on Composition API primitives: a shallowRef holds the live ECharts instance, and a cluster of watch/watchSyncEffect calls reacts to changes in option, theme, initOptions, group, and manualUpdate to drive init(), applyOption(), or a full cleanup()+init() reinitialization. Cross-cutting concerns are factored into composables under src/composables/ (useAutoresize, useLoading, useSlotOption, usePublicAPI) and src/core/events.ts (reactive listener binding, attribute forwarding), keeping the main component focused on orchestration rather than each concern’s implementation. The src/graphic/ subtree is a self-contained extension (collector, runtime, component-factory, mount) that only activates if imported, so the base bundle pays no cost for graphic-slot support. A dedicated src/update.ts module builds a structural “signature” of each option (top-level array/component shapes, $action detection) purely to decide the safest setOption call, decoupling update-strategy logic from the component itself. This separation of lifecycle orchestration, side-effect composables, and update planning is what lets the component support manual mode, graphic overlays, SSR, and Web Component registration without the core setup() function becoming unmanageable.

Tech Stack Written in TypeScript against Vue 3.5+ (Composition API, defineComponent, shallowRef, watchSyncEffect) with echarts 6.x as a peer dependency (only echarts/core is imported directly, keeping chart/series/renderer selection in the consumer’s hands). The library is bundled with tsdown and typechecked with vue-tsc/tsc against multiple tsconfig targets (library, package, package-echarts), and ships CJS-free ESM output plus unpkg/jsdelivr UMD-style entries for CDN use. Linting and formatting run through oxlint/oxfmt rather than ESLint/Prettier, and publint validates the published package shape before release. A Vite-powered demo/ app doubles as a manual test and documentation playground.

Code Quality The test suite (tests/) is split into .node.test.ts and .browser.test.ts projects under Vitest, the latter running in real Chromium via Playwright and vitest-browser-vue, with Istanbul coverage reporting. Tests are organized by concern (echarts, graphic-slot-*, autoresize, ssr, update, wc, codegen) rather than one monolithic file, and a tests/TESTING.md documents the split explicitly. Error handling favors explicit runtime checks (e.g. throwing from the public API proxy if the chart is disposed or not yet initialized) over silent failures, and an AGENTS.md codifies naming, formatting, and PR conventions for contributors. CI (.github/workflows/ci.yml) runs lint, typecheck, and build on every change, and the project is written entirely in TypeScript with strict per-target tsconfig files.

API Design The public surface is intentionally small: a single VChart component plus three injection keys (THEME_KEY, INIT_OPTIONS_KEY, UPDATE_OPTIONS_KEY) and a documented event list mirroring ECharts’ own event names, so anyone who knows ECharts’ imperative API can guess the component’s behavior. Escape hatches are deliberate rather than accidental: manual-update plus a template-ref-exposed setOption gives direct imperative control when the automatic planner isn’t the right fit, and the public API surface (getWidth, convertToPixel, dispatchAction, etc.) is generated by proxying a fixed method list onto the live instance rather than reimplementing each method, keeping it in lockstep with ECharts itself. Getting started requires only npm install echarts vue-echarts and a template using <VChart :option="option" />, with an official codegen tool to generate on-demand import statements for consumers who want a smaller bundle.