Vue 3 ApexCharts Component

Common errors

• Failed to resolve component: apexchart

  cause The `<apexchart>` component was not properly registered either globally or locally.
  fix If using globally, ensure `import VueApexCharts from "vue3-apexcharts"; createApp(App).use(VueApexCharts).mount('#app');` is called. If locally, add `components: { apexchart: VueApexCharts }` to your component's definition.

• Cannot read properties of undefined (reading 'render')

  cause The underlying `apexcharts` core library is not installed or not accessible to `vue3-apexcharts`.
  fix Install `apexcharts` as a peer dependency: `npm install apexcharts` or `yarn add apexcharts`.

• Property '$apexcharts' does not exist on type 'ComponentPublicInstance<...>' (TypeScript error)

  cause The TypeScript type declaration for the global `$apexcharts` property is missing from your project.
  fix Add the provided `declare module "@vue/runtime-core" {...}` block to your TypeScript environment (e.g., in `shims-vue.d.ts` or `main.ts`) after importing `ApexCharts`.

Warnings

• breaking vue3-apexcharts is exclusively for Vue 3.x applications. Attempting to use it in a Vue 2.x project will result in compatibility errors and runtime failures.
  Fix: For Vue 2.x applications, use the `vue-apexcharts` package instead. Ensure your project's `vue` dependency is `^3.0.0` or higher.
• gotcha The `apexcharts` core library is a peer dependency and must be installed separately. The `vue3-apexcharts` component will not render or function correctly if `apexcharts` is missing.
  Fix: Install `apexcharts` alongside `vue3-apexcharts`: `npm install apexcharts vue3-apexcharts` or `yarn add apexcharts vue3-apexcharts`.
• gotcha For global component registration, `app.use(VueApexCharts)` must be called *before* mounting the Vue application. If you register locally, ensure `apexchart: VueApexCharts` is correctly declared in your component's `components` option.
  Fix: Ensure `app.use(VueApexCharts)` is executed directly after `createApp(App)` in your `main.ts`/`main.js` file, or explicitly add `apexchart: VueApexCharts` to the `components` property of any Vue component using it.
• gotcha When using TypeScript and attempting to access `$apexcharts` on the Vue instance (e.g., `this.$apexcharts`), you need to augment the `ComponentCustomProperties` interface to provide type declarations, otherwise TypeScript will report an error.
  Fix: Add the following declaration to a `.d.ts` file or directly in your `main.ts` after importing `ApexCharts`: ```typescript import ApexCharts from "apexcharts"; declare module "@vue/runtime-core" { interface ComponentCustomProperties { $apexcharts: typeof ApexCharts; } } ```

Install

• npm install vue3-apexcharts npm
• yarn add vue3-apexcharts yarn
• pnpm add vue3-apexcharts pnpm

Imports

• VueApexCharts
  wrong:

  import { VueApexCharts } from 'vue3-apexcharts';

  correct:

  import VueApexCharts from "vue3-apexcharts";
  const app = createApp(App);
  app.use(VueApexCharts);

  The main component is a default export, typically used for global registration via `app.use()`.
• apexchart (component)
  wrong:

  const apexchart = require('vue3-apexcharts');

  correct:

  import VueApexCharts from "vue3-apexcharts";
  export default {
    components: {
      apexchart: VueApexCharts
    },
  };

  For local component registration within a specific Vue component. Vue 3 projects are primarily ESM-based, so `require()` is incorrect.
• $apexcharts (global property)
  wrong:

  app.config.globalProperties.$apexcharts = ApexCharts; // (without TS declaration)

  correct:

  import ApexCharts from "apexcharts";
  app.config.globalProperties.$apexcharts = ApexCharts;
  
  declare module "@vue/runtime-core" {
    interface ComponentCustomProperties {
      $apexcharts: typeof ApexCharts;
    }
  }

  Required for TypeScript to provide type safety and intellisense when accessing the global `$apexcharts` instance on `this` within Vue components.

Quickstart

This example demonstrates how to create a reactive bar chart using `vue3-apexcharts`, configure its data and options, and dynamically update the chart series when a button is clicked. It includes both local component registration and TypeScript type declaration for the global `$apexcharts` property, making it ready for a modern Vue 3 setup.

<template>
  <div class="app">
    <apexchart
      width="550"
      type="bar"
      :options="chartOptions"
      :series="series"
    ></apexchart>
    <div>
      <button @click="updateChart">Update Chart Data</button>
    </div>
  </div>
</template>

<script lang="ts">
import { defineComponent } from 'vue';
import VueApexCharts from "vue3-apexcharts";
import ApexCharts from "apexcharts"; // For global property typing

// Add this when into a TypeScript codebase to type $apexcharts
declare module "@vue/runtime-core" {
  interface ComponentCustomProperties {
    $apexcharts: typeof ApexCharts;
  }
}

export default defineComponent({
  components: {
    apexchart: VueApexCharts, // Local registration, or use app.use(VueApexCharts) globally in main.ts
  },
  data() {
    return {
      chartOptions: {
        chart: {
          id: "vuechart-example",
          toolbar: {
            show: false
          }
        },
        xaxis: {
          categories: [1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998]
        },
        title: {
          text: 'Yearly Data Series',
          align: 'left'
        }
      },
      series: [
        {
          name: "Series A",
          data: [30, 40, 35, 50, 49, 60, 70, 91]
        }
      ]
    };
  },
  methods: {
    updateChart() {
      // Simulate data update by generating new random data
      const newSeriesData = this.series[0].data.map(() => Math.floor(Math.random() * (100 - 20 + 1)) + 20);
      this.series = [{ name: "Series A", data: newSeriesData }];
    }
  }
});
</script>

<style>
.app {
  font-family: Avenir, Helvetica, Arial, sans-serif;
  text-align: center;
  color: #2c3e50;
  margin-top: 60px;
}
button {
  padding: 10px 20px;
  margin-top: 20px;
  cursor: pointer;
  background-color: #42b983;
  color: white;
  border: none;
  border-radius: 5px;
}
</style>