vue-chartjs: the thin Vue layer most teams end up writing themselves

Why a wrapper exists at all when Chart.js already runs in a browser

Chart.js is a framework-agnostic canvas library. It builds a chart from a config object and hands you an instance you mutate by hand. In Vue that produces two problems. The first is teardown: a chart holds a canvas, an animation frame loop and a resize observer, and none of that is cleaned up when a component unmounts. The second is ergonomics: every call site ends up with the same `new Chart(canvas, config)` boilerplate and its own `onUnmounted` handler.

vue-chartjs exists to solve both, and its design is the minimum intervention that does so. Each chart type is exported as a Vue component, so `Bar`, `Line`, `Doughnut` and the rest become ordinary template elements. The component owns the lifecycle, and you pass data and options as props.

The project description says it plainly: a Vue.js wrapper for Chart.js for creating charts you can reuse as components. The name is inspired by nothing clever, and the scope is deliberately narrow. It is not a theming system, not a dashboard framework, and not an abstraction over multiple charting libraries. Anyone reaching for it expecting the second category will find a much smaller thing.

Installing the pair and registering only the chart types you use

The install is two packages, because the wrapper deliberately does not bundle the library it wraps. That is the single most important design decision here, and it is the reason the README tells you to install with peer dependencies:

pnpm add vue-chartjs chart.js
# or
yarn add vue-chartjs chart.js
# or
npm i vue-chartjs chart.js

You always need both. Then you register the Chart.js pieces yourself, which looks like boilerplate until you notice what it buys. Chart.js v4 is tree-shakeable, so registering only `BarElement`, `CategoryScale` and `LinearScale` instead of everything means only that code reaches the browser. The wrapper cannot do this for you, because the registration call is a module-level side effect in Chart.js and the wrapper has no idea which of your components mount.

The package is published as ESM with a separate CommonJS build. In `package.json` the package sets `type` to `module`, points `exports` at the TypeScript source during development, and uses a `publishConfig` block that swaps in `./dist/index.cjs`, `./dist/index.js` and generated type declarations for consumers. The shipped `files` array is just `dist`, and `sideEffects` is false, which is the field that lets a bundler drop the import entirely when you do not use it.

The component usage the README puts front and centre

The quick start gives you one complete component rather than fragments, which is the right choice for a README because the point of the wrapper is that the whole example fits on a screen. The template declares the chart, the script registers the pieces Chart.js needs, and the data and options live in the component's own state:

<template>
  <Bar :data="data" :options="options" />
</template>

<script lang="ts">
import {
  Chart as ChartJS,
  Title,
  Tooltip,
  Legend,
  BarElement,
  CategoryScale,
  LinearScale
} from 'chart.js'

The example registers `CategoryScale`, `LinearScale`, `BarElement`, `Title`, `Tooltip` and `Legend`, which is the minimum for a bar chart with axes and a legend. If you skip `Title`, `responsive: true` still works, but you will find that Chart.js logs a warning about an unregistered component as soon as anything tries to use it.

Two details are worth noticing. The chart type is chosen by which component you import rather than by a string prop, so there is no `type: 'bar'` to mistype. And the props are named `data` and `options`, matching Chart.js's own vocabulary, so the documentation for the underlying library transfers directly to the wrapper.

Version 5 rewrote how charts react to data changes

The README links two separate migration guides, one for v4 to v5 and one from the older `vue-chart-3` package, and that is a signal about how much moved. v5 is a rebuild rather than an incremental release, and the reactivity question is where the work went.

The README's own documentation index lists reactivity as the first guide, with updating charts as the anchor, and separately lists access to the Chart instance. Those two pages together tell you the shape of the API: you update a chart by changing the data you pass, and when you need to reach the underlying Chart.js object, you get the instance through the component's ref rather than by reaching into the DOM yourself.

The release history shows the v5 line settling. v5.3.2 landed in October 2024 and was mostly dependency work plus a change to the typed chart definitions. v5.3.3 in November 2025 fixed aria labels and the website's CI. v5.3.4 on 2026-07-07 fixed a specific and nasty bug: the chart instance ref stayed null under Vue 3.5.39. That last one is the kind of fix worth reading before you adopt a version, because a null ref means the escape hatch to the Chart.js instance silently does nothing on a particular Vue patch release. The repository's `package.json` still carries 5.3.4, and the last push was on 2026-09-15.

What the repository reveals about how the package is built

The tree is small and mostly tooling, which is what a library like this should look like. `src/` holds the components, `test/` the unit tests, and `stories/` plus a `.storybook/` directory the visual component catalogue. There is a `sandboxes/` directory for runnable examples and a `website/` directory that backs the documentation site at vue-chartjs.org.

The build is Rollup with TypeScript declarations emitted separately. The scripts make the sequence explicit: `build` runs `rollup -c` alongside `emitDeclarations`, which in turn runs `tsc --emitDeclarationOnly`. Unit tests run under Vitest with coverage, `start:storybook` serves the story catalogue on port 6006, and `lint` runs ESLint across `sandboxes/`, `src/`, `stories/` and `test/`. There is also a `.size-limit.json`, which is the configuration for asserting the bundle size budget, and a `codecov.yml` plus a `.codeclimate.yml` for coverage and static analysis reporting.

You can reproduce the whole pipeline locally with the commands the README lists under build setup:

pnpm install
pnpm build
pnpm test:unit
pnpm test

The commit tooling is equally opinionated: `.commitlintrc.json` defines the message format, `.czrc` configures commitizen, `.nano-staged.json` and `.simple-git-hooks.json` wire up pre-commit formatting and hooks. That is a lot of infrastructure for a wrapper of this size, and it is all aimed at making the published artifact small and its types correct.

Where this approach stops and Chart.js itself takes over

The honest limit of vue-chartjs is that everything past the component boundary is Chart.js. Animations, scales, tick callbacks, custom plugins, legend positioning and canvas sizing are all configured through the options object you pass in, and the wrapper does not restyle, validate or wrap any of it. If your question is how to do something with a chart, the answer is in the Chart.js documentation, not on vue-chartjs.org.

Accessibility is the one area where the wrapper takes its own position. The README links a dedicated accessibility guide alongside the migration guides, and the v5.3.3 release fixed aria labels, which suggests the canvas-based rendering needs deliberate help rather than coming for free. A canvas element has no semantics of its own, so a chart that only works visually will fail an accessibility audit regardless of how tidy the component code is. Read that guide before you ship a dashboard.

There is also a vendor signal worth naming plainly. The README suggests Cube, an API for data apps, under a referral link, alongside donation badges for PayPal and Ko-fi. That does not affect what the library does, and it is normal for a small open source project to survive on sponsorship, but it does tell you who maintains it. The listed maintainer is a single developer with two named contributors, so the bus factor is one. For a chart wrapper that is usually acceptable. For a design system at a large company, read the code first.

Editorial conclusion

vue-chartjs earns its place in a Vue 3 codebase that has decided on Chart.js, because the per-chart imports it asks you to write are exactly the ones you would otherwise write badly by hand. It is the wrong choice if you are still on Vue 2 or if you need SSR chart rendering, since neither is addressed anywhere in the repository. Three things to check first: that the reactivity behaviour on vue-chartjs.org matches how you mutate your data, that your Vue version is recent enough to be covered by the v5.3.4 fix for the null chart ref under Vue 3.5.39, and that the accessibility guidance suits your audit requirements. Start with the quick start below, then read the reactivity page before wiring charts to live data.

Frequently asked questions

Official sources

1. apertureless/vue-chartjs on GitHub
2. License: MIT
3. Project website
4. README
5. Releases