Vue Chart.js 4 Wrapper

Common errors

• Error: "Chart with ID '0' is already registered"

  cause Attempting to register Chart.js components (e.g., `registerables`) multiple times, typically by calling `Chart.register()` in every component instance.
  fix Ensure `Chart.register(...registerables);` is called only once globally in your application's entry file (e.g., `main.ts` or a Vue plugin) before any chart components are mounted.

• [Vue warn]: Failed to resolve component: <ChartType>

  cause A `vue-chart-3` component (e.g., `<LineChart>`) was used in a template but not imported or registered with Vue.
  fix Import the desired chart component from `vue-chart-3` (e.g., `import { LineChart } from 'vue-chart-3';`) and declare it in your Vue component's `components` option, or use it directly in a `<script setup>` context.

• TypeError: Cannot read properties of undefined (reading 'scales') (or similar Chart.js internal errors)

  cause Specific Chart.js elements like scales, tooltips, or legend controllers were not registered with the global `Chart` object.
  fix Import `Chart` and `registerables` from `chart.js` and call `Chart.register(...registerables);` once globally. For tree-shaking, import and register only the necessary components from `chart.js` (e.g., `CategoryScale`, `LinearScale`, `Tooltip`, `Legend`, `BarElement`).

• npm ERR! ERESOLVE unable to resolve dependency tree

  cause Mismatched or missing peer dependencies for `chart.js` or `vue`.
  fix Ensure your project's `package.json` explicitly lists `"chart.js": "^4.0.0"` and `"vue": ">= 3"` in `dependencies` and install them. Use `npm install --force` or `npm install --legacy-peer-deps` as a last resort, but first, verify compatible versions.

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax in an ES module (`type: "module"` in `package.json`) environment, or when the bundler expects ESM.
  fix Always use ES module `import` syntax (e.g., `import { BarChart } from 'vue-chart-3';`) as `vue-chart-3` supports ESM builds since v3.1.0 and is a modern Vue 3 library.

Warnings

• breaking Version 4.0.0 represents a major breaking change, requiring Chart.js v4 and Vue 3.5+. Projects using older versions of Chart.js (v3 or earlier) or Vue 2.x must migrate their dependencies.
  Fix: Ensure `chart.js` is `^4.0.0` and `vue` is `>= 3`. Follow the migration guide for Chart.js v4 and Vue 3 if upgrading from older major versions.
• breaking Chart.js v4, and by extension `vue-chart-3` v4, adopts a tree-shakable architecture. This means core Chart.js elements (controllers, scales, tooltips, etc.) must be explicitly imported and registered, typically once globally, using `Chart.register(...registerables);` or individual imports.
  Fix: Add `import { Chart, registerables } from 'chart.js'; Chart.register(...registerables);` at your application's entry point or in a global plugin. Alternatively, import and register specific Chart.js modules for smaller bundle sizes.
• gotcha `vue-chart-3` relies on `chart.js` and `vue` as peer dependencies. Incorrect or incompatible versions of these peer dependencies will lead to installation issues or runtime errors. The package requires Node.js >= 20.
  Fix: Install `chart.js` with `^4.0.0` and `vue` with `>= 3` alongside `vue-chart-3`. Verify your Node.js version meets the `>=20` requirement.
• gotcha Prior to versions 3.1.5, 3.1.6, and 3.1.7, `vue-chart-3` had known reactivity issues where updates to chart data or options props might not correctly trigger chart re-renders.
  Fix: Ensure you are using `vue-chart-3` version 3.1.8 or higher, or the latest 4.x release, to benefit from improved reactivity watchers.
• deprecated The `extends` and mixin-based approach for creating charts, common in `vue-chartjs` v3, has been removed in `vue-chart-3` v4. Charts are now standard Vue 3 components used directly with props.
  Fix: Refactor chart components to import and use the specific `vue-chart-3` components (e.g., `<BarChart>`) directly, passing `chartData` and `options` as props.

Install

• npm install vue-chart-3 npm
• yarn add vue-chart-3 yarn
• pnpm add vue-chart-3 pnpm

Imports

• LineChart
  wrong:

  import LineChart from 'vue-chart-3/LineChart';

  correct:

  import { LineChart } from 'vue-chart-3';

  Import specific chart components as named exports. Check documentation for all available chart types like BarChart, DoughnutChart, etc.
• Chart
  wrong:

  import Chart from 'chart.js';

  correct:

  import { Chart, registerables } from 'chart.js';

  The core Chart.js object and `registerables` are imported directly from `chart.js` for tree-shaking and global registration. Chart.js v4 requires explicit registration of controllers, elements, scales, and plugins.
• useChart

  import { useLineChart } from 'vue-chart-3';

  While `vue-chart-3` primarily uses components, it also provides hooks like `useLineChart` (and similar for other types) for advanced use cases where direct Chart.js instance manipulation or custom rendering is needed. This is less common for basic usage.

Quickstart

This quickstart demonstrates how to set up and render a reactive Bar Chart using `vue-chart-3` and Chart.js in a Vue 3 Composition API component, including global Chart.js registration and dynamic data updates.

import { defineComponent, ref, computed } from 'vue';
import { Chart, registerables } from 'chart.js';
import { BarChart } from 'vue-chart-3';

// Globally register Chart.js components once
Chart.register(...registerables);

export default defineComponent({
  name: 'SimpleBarChart',
  components: {
    BarChart,
  },
  setup() {
    const dataValues = ref([65, 59, 80, 81, 56, 55, 40]);

    const chartData = computed(() => ({
      labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'],
      datasets: [
        {
          label: 'Data One',
          backgroundColor: '#42b983',
          data: dataValues.value,
        },
        {
          label: 'Data Two',
          backgroundColor: '#ff6384',
          data: [28, 48, 40, 19, 86, 27, 90],
        },
      ],
    }));

    const chartOptions = ref({
      responsive: true,
      maintainAspectRatio: false,
      plugins: {
        title: {
          display: true,
          text: 'Monthly Sales Data',
        },
      },
    });

    const updateData = () => {
      dataValues.value = dataValues.value.map(value => Math.floor(Math.random() * 100));
    };

    return {
      chartData,
      chartOptions,
      updateData,
    };
  },
  template: `
    <div :style="{ height: '400px', width: '600px' }">
      <BarChart :chartData="chartData" :options="chartOptions" />
      <button @click="updateData" style="margin-top: 20px; padding: 10px 20px; background-color: #42b983; color: white; border: none; border-radius: 5px; cursor: pointer;">Update Data</button>
    </div>
  `,
});