Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore: update docs
Browse files Browse the repository at this point in the history
apertureless committed Oct 31, 2024
1 parent f1e6391 commit b43dd80
Showing 51 changed files with 30,061 additions and 3,962 deletions.
3 changes: 2 additions & 1 deletion website/package.json
Original file line number Diff line number Diff line change
@@ -2,11 +2,12 @@
"name": "website",
"version": "0.0.0",
"private": true,
"type": "module",
"scripts": {
"dev": "vitepress dev src",
"build": "vitepress build src"
},
"devDependencies": {
"vitepress": "^0.22.3"
"vitepress": "^1.4.3"
}
}
1,184 changes: 947 additions & 237 deletions website/pnpm-lock.yaml

Large diffs are not rendered by default.

282 changes: 282 additions & 0 deletions website/src/.vitepress/cache/deps/@theme_index.js

Large diffs are not rendered by default.

7 changes: 7 additions & 0 deletions website/src/.vitepress/cache/deps/@theme_index.js.map

Large diffs are not rendered by default.

40 changes: 40 additions & 0 deletions website/src/.vitepress/cache/deps/_metadata.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
{
"hash": "0c87bf3b",
"configHash": "537ebdcd",
"lockfileHash": "17c814b1",
"browserHash": "7f9e4657",
"optimized": {
"vue": {
"src": "../../../../../node_modules/.pnpm/vue@3.2.45/node_modules/vue/dist/vue.runtime.esm-bundler.js",
"file": "vue.js",
"fileHash": "81e7f501",
"needsInterop": false
},
"vitepress > @vue/devtools-api": {
"src": "../../../../node_modules/.pnpm/@vue+devtools-api@7.6.1/node_modules/@vue/devtools-api/dist/index.js",
"file": "vitepress___@vue_devtools-api.js",
"fileHash": "f18838d4",
"needsInterop": false
},
"vitepress > @vueuse/core": {
"src": "../../../../node_modules/.pnpm/@vueuse+core@11.2.0_vue@3.5.12_typescript@5.6.3_/node_modules/@vueuse/core/index.mjs",
"file": "vitepress___@vueuse_core.js",
"fileHash": "005e74d6",
"needsInterop": false
},
"@theme/index": {
"src": "../../../../node_modules/.pnpm/vitepress@1.4.3_@algolia+client-search@4.24.0_postcss@8.4.47_search-insights@2.17.2_typescript@5.6.3/node_modules/vitepress/dist/client/theme-default/index.js",
"file": "@theme_index.js",
"fileHash": "a7aaf44d",
"needsInterop": false
}
},
"chunks": {
"chunk-PWVUJGW4": {
"file": "chunk-PWVUJGW4.js"
},
"chunk-6J5AW4SK": {
"file": "chunk-6J5AW4SK.js"
}
}
}
11,547 changes: 11,547 additions & 0 deletions website/src/.vitepress/cache/deps/chunk-6J5AW4SK.js

Large diffs are not rendered by default.

7 changes: 7 additions & 0 deletions website/src/.vitepress/cache/deps/chunk-6J5AW4SK.js.map

Large diffs are not rendered by default.

10,000 changes: 10,000 additions & 0 deletions website/src/.vitepress/cache/deps/chunk-PWVUJGW4.js

Large diffs are not rendered by default.

7 changes: 7 additions & 0 deletions website/src/.vitepress/cache/deps/chunk-PWVUJGW4.js.map

Large diffs are not rendered by default.

3 changes: 3 additions & 0 deletions website/src/.vitepress/cache/deps/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"type": "module"
}
5,026 changes: 5,026 additions & 0 deletions website/src/.vitepress/cache/deps/vitepress___@vue_devtools-api.js

Large diffs are not rendered by default.

Large diffs are not rendered by default.

569 changes: 569 additions & 0 deletions website/src/.vitepress/cache/deps/vitepress___@vueuse_core.js

Large diffs are not rendered by default.

295 changes: 295 additions & 0 deletions website/src/.vitepress/cache/deps/vue.js
7 changes: 7 additions & 0 deletions website/src/.vitepress/cache/deps/vue.js.map
89 changes: 89 additions & 0 deletions website/src/.vitepress/config.mts
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
import { defineConfig } from 'vitepress'

export default defineConfig({
lastUpdated: true,

themeConfig: {
editLink: {
pattern:
'https://github.com/apertureless/vue-chartjs/edit/main/website/src/:path'
},
search: {
provider: 'algolia',
options: {
indexName: 'vue-chartjs',
apiKey: 'a1bb4528e8ed1eb89e40d6e4c1000514',
appId: '24VA3R3NCC'
}
},

nav: [
{ text: 'Guide', link: '/guide/', activeMatch: '^/guide/' },
{
text: 'Migration guides',
link: '/migration-guides/',
activeMatch: '^/migration-guides/'
},
{
text: 'API',
link: '/api/',
activeMatch: '^/api/'
},
{
text: 'Examples',
link: '/examples/',
activeMatch: '^/examples/'
},
{
text: 'Stack Overflow',
link: 'https://stackoverflow.com/questions/tagged/vue-chartjs/'
},
{
text: 'Github',
link: 'https://github.com/apertureless/vue-chartjs'
}
],

sidebar: [
{
text: 'Introduction',
items: [
{ text: 'Getting started', link: '/guide' },
{ text: 'Examples', link: '/guide/examples' }
]
},
{
text: 'Migration',
items: [
{ text: 'Introduction', link: '/migration-guides/' },
{ text: 'Migrate to v5', link: '/migration-guides/v5' },
{ text: 'Migrate to v4', link: '/migration-guides/v4' },
{
text: 'Migrate from vue-chart-3',
link: '/migration-guides/vue-chart-3'
}
]
}
],
footer: {
message: 'Released under the MIT License.',
copyright: 'Copyright © 2019-present Jakub Juszczak'
}
},

locales: {
root: {
label: 'English',
lang: 'en-US',
title: '📈 vue-chartjs',
description: '⚡ Easy and beautiful charts with Chart.js and Vue.js'
},
de: {
label: 'Deutsch',
lang: 'de',
link: '/de/',
title: '📈 vue-chartjs',
description: '⚡Einfache und schöne Diagramme mit Chart.js und Vue.js'
}
}
})
135 changes: 0 additions & 135 deletions website/src/.vitepress/config.ts

This file was deleted.

34 changes: 34 additions & 0 deletions website/src/de/api/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Coding Reference

## Props

Some basic props are defined in the components provided by `vue-chartjs`.

| Prop | Description |
|---|---|
| data | Data object that is passed into the Chart.js chart |
| options | Options object that is passed into the Chart.js chart |
| datasetIdKey | Key name to identify the dataset |
| plugins | Plugins array that is passed into the Chart.js chart |
| updateMode | Mode string to indicate the transition configuration to be used. |
| ariaLabel | An [ARIA label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) that describes the chart to make it accessible. |
| ariaDescribedby | A reference to the [describing element](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby). E. g. a table representation of the data. |

The rest of the props will fall through to the canvas element.

## Global Methods

Global Methods need to be imported.

### createTypedChart

- **Type:** `Function`
- **Arguments**:`chart-type`, `chart-controller`
- **Usage:**

```js
import { createTypedChart } from 'vue-chartjs'
import { LineController } from 'chart.js'

const CustomLine = createTypedChart('line', LineController)
```
26 changes: 26 additions & 0 deletions website/src/de/examples/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Examples

## Vue 3 charts

- [Bar](https://stackblitz.com/github/apertureless/vue-chartjs/tree/main/sandboxes/bar)
- [Bubble](https://stackblitz.com/github/apertureless/vue-chartjs/tree/main/sandboxes/bubble)
- [Doughnut](https://stackblitz.com/github/apertureless/vue-chartjs/tree/main/sandboxes/doughnut)
- [Line](https://stackblitz.com/github/apertureless/vue-chartjs/tree/main/sandboxes/line)
- [Pie](https://stackblitz.com/github/apertureless/vue-chartjs/tree/main/sandboxes/pie)
- [PolarArea](https://stackblitz.com/github/apertureless/vue-chartjs/tree/main/sandboxes/polar-area)
- [Radar](https://stackblitz.com/github/apertureless/vue-chartjs/tree/main/sandboxes/radar)
- [Scatter](https://stackblitz.com/github/apertureless/vue-chartjs/tree/main/sandboxes/scatter)
- [Bar with reactive data](https://stackblitz.com/github/apertureless/vue-chartjs/tree/main/sandboxes/reactive)
- [Custom chart](https://stackblitz.com/github/apertureless/vue-chartjs/tree/main/sandboxes/custom)
- [Events](https://stackblitz.com/github/apertureless/vue-chartjs/tree/main/sandboxes/events)

## Vue 2 charts (vue-chartjs v4)

- [Bar](https://codesandbox.io/s/github/apertureless/vue-chartjs/tree/v4/legacy/sandboxes/bar)
- [Bubble](https://codesandbox.io/s/github/apertureless/vue-chartjs/tree/v4/legacy/sandboxes/bubble)
- [Doughnut](https://codesandbox.io/s/github/apertureless/vue-chartjs/tree/v4/legacy/sandboxes/doughnut)
- [Line](https://codesandbox.io/s/github/apertureless/vue-chartjs/tree/v4/legacy/sandboxes/line)
- [Pie](https://codesandbox.io/s/github/apertureless/vue-chartjs/tree/v4/legacy/sandboxes/pie)
- [PolarArea](https://codesandbox.io/s/github/apertureless/vue-chartjs/tree/v4/legacy/sandboxes/polar-area)
- [Radar](https://codesandbox.io/s/github/apertureless/vue-chartjs/tree/v4/legacy/sandboxes/radar)
- [Scatter](https://codesandbox.io/s/github/apertureless/vue-chartjs/tree/v4/legacy/sandboxes/scatter)
189 changes: 189 additions & 0 deletions website/src/de/guide/examples.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,189 @@

# Examples

## Chart with props

Your goal should be to create reusable chart components. For this purpose, you should utilize Vue.js props to pass in chart options and chart data. This way, the parent component itself does not hold an opinion about fetching data and is only for presentation.

```vue
<template>
<Bar :data="chartData" :options="chartOptions" />
</template>
<script>
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
props: {
chartData: {
type: Object,
required: true
},
chartOptions: {
type: Object,
default: () => {}
}
}
}
</script>
```

## Chart with local data

You can handle your chart data directly in your parent component.

```vue
<template>
<Bar :data="chartData" />
</template>
<script>
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
data() {
return {
chartData: {
labels: [ 'January', 'February', 'March'],
datasets: [
{
label: 'Data One',
backgroundColor: '#f87979',
data: [40, 20, 12]
}
]
}
}
}
}
</script>
```

## Chart with API data

A common pattern is to use an API to retrieve your data. However, there are some things to keep in mind. The most common problem is that you mount your chart component directly and pass in data from an asynchronous API call. The problem with this approach is that Chart.js tries to render your chart and access the chart data synchronously, so your chart mounts before the API data arrives.

To prevent this, a simple `v-if` is the best solution.

Create your chart component with a data prop and options prop, so we can pass in our data and options from a container component.

```vue
<template>
<div class="container">
<Bar v-if="loaded" :data="chartData" />
</div>
</template>
<script>
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
data: () => ({
loaded: false,
chartData: null
}),
async mounted () {
this.loaded = false
try {
const { userlist } = await fetch('/api/userlist')
this.chartdata = userlist
this.loaded = true
} catch (e) {
console.error(e)
}
}
}
</script>
```

## Chart with dynamic styles

You can set `responsive: true` and pass in a styles object which gets applied as inline styles to the outer `<div>`. This way, you can change the height and width of the outer container dynamically, which is not the default behaviour of Chart.js. It is best to use computed properties for this.

::: warning
You need to set `position: relative`
:::

```vue
<template>
<div>
<Bar :style="myStyles"/>
</div>
</template>
<script>
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
computed: {
myStyles () {
return {
height: `${/* mutable height */}px`,
position: 'relative'
}
}
}
}
</script>
```

## Custom / New Charts

Sometimes you need to extend the default Chart.js charts. There are a lot of [examples](http://www.chartjs.org/docs/latest/developers/charts.html) on how to extend and modify the default charts. Or, you can create your own chart type.

In `vue-chartjs`, you can do this pretty much the same way:

```js
// 1. Import Chart.js so you can use the global Chart object
import { Chart } from 'chart.js'
// 2. Import the `createTypedChart()` method to create the vue component.
import { createTypedChart } from 'vue-chartjs'
// 3. Import needed controller from Chart.js
import { LineController } from 'chart.js'

// 3. Extend one of the default charts
// http://www.chartjs.org/docs/latest/developers/charts.html
class LineWithLineController extends LineController { /* custom magic here */}

// 4. Generate the vue-chartjs component
// The first argument is the chart-id, the second the chart type, third is the custom controller
const CustomLine = createTypedChart('line', LineWithLineController)

// 5. Extend the CustomLine Component just like you do with the default vue-chartjs charts.

export default {
components: { CustomLine }
}
```

## Resources

Here are some resources, such as tutorials, on how to use `vue-chartjs`:

- [Using vue-chartjs with WordPress](https://medium.com/@apertureless/wordpress-vue-and-chart-js-6b61493e289f)
- [Create stunning Charts with Vue and Chart.js](https://hackernoon.com/creating-stunning-charts-with-vue-js-and-chart-js-28af584adc0a)
- [Let’s Build a Web App with Vue, Chart.js and an API Part I](https://hackernoon.com/lets-build-a-web-app-with-vue-chart-js-and-an-api-544eb81c4b44)
- [Let’s Build a Web App with Vue, Chart.js and an API Part II](https://hackernoon.com/lets-build-a-web-app-with-vue-chart-js-and-an-api-part-ii-39781b1d5acf)
- [Build a realtime chart with VueJS and Pusher](https://blog.pusher.com/build-realtime-chart-with-vuejs-pusher/)
210 changes: 210 additions & 0 deletions website/src/de/guide/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,210 @@
# Getting Started

**vue-chartjs** is a wrapper for [Chart.js](https://github.com/chartjs/Chart.js) in Vue. You can easily create reuseable chart components.

Supports Chart.js v4.

## Introduction

`vue-chartjs` lets you use Chart.js without much hassle inside Vue. It's perfect for people who need simple charts up and running as fast as possible.

It abstracts the basic logic but exposes the Chart.js object to give you maximal flexibility.

:::tip Need an API to fetch data?
Please consider [Cube](https://cube.dev/?ref=eco-vue-chartjs), an open-source API for data apps.
:::

## Installation

You can install `vue-chartjs` over `yarn` or `npm` or `pnpm`. However, you also need to add `chart.js` as a dependency to your project because `Chart.js` is a peerDependency. This way you can have full control over the versioning of `Chart.js`.

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

## Integration

Every chart type that is available in Chart.js is exported as a named component and can be imported as such. These components are normal Vue components.

The idea behind vue-chartjs is to provide easy-to-use components, with maximal flexibility and extensibility.

## Creating your first Chart

First, you need to import the base chart.

```javascript
import { Bar } from 'vue-chartjs'
```

Check out the official [Chart.js docs](http://www.chartjs.org/docs/latest/#creating-a-chart) to see the object structure you need to provide.

Just create your own component.

**BarChart.vue**

```vue
<template>
<Bar
id="my-chart-id"
:options="chartOptions"
:data="chartData"
/>
</template>
<script>
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
data() {
return {
chartData: {
labels: [ 'January', 'February', 'March' ],
datasets: [ { data: [40, 20, 12] } ]
},
chartOptions: {
responsive: true
}
}
}
}
</script>
```

Use it in your vue app:

**App.vue**

```vue
<template>
<BarChart />
</template>
<script>
import BarChart from 'path/to/component/BarChart'
export default {
name: 'App',
components: { BarChart }
}
</script>
```

## Updating Charts

Since v4 charts have data change watcher and options change watcher by default. Wrapper will update or re-render the chart if new data or new options is passed. Mixins have been removed.

```vue
<template>
<Bar :data="chartData" :options="chartOptions" />
</template>
<script>
// DataPage.vue
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
computed: {
chartData() { return /* mutable chart data */ },
chartOptions() { return /* mutable chart options */ }
}
}
</script>
```

You may get Vue's `Target is readonly` warnings when you are updating your `chartData`.

If your `chartData` is a `read-only` reactive value, you can override this warning by using a clone:

```vue
<template>
<Bar :data="JSON.stringify(JSON.parse(chartData))" :options="chartOptions" />
</template>
```

Unless you have a writable computed `chartData`, you won't be able to use the newer `structuredClone`, as you'll likely hit the `Write operation failed: computed value is readonly` error.

You don't need to use a clone if your `chartData` is a [writable computed value](https://vuejs.org/guide/essentials/computed#writable-computed).



## Access to Chart instance

You can get access to chart instance via template refs.

```vue
<template>
<BarChart ref="bar" />
</template>
```

In Vue3 projects:

```javascript
const chartInstance = this.$refs.bar.chart
```

## Accessibility

To make your charts accessible to all users, you should label your charts.
Please refer also to the official [Chart.js Accessibility notes](https://www.chartjs.org/docs/latest/general/accessibility.html).

### `aria-label`

You can directly label a chart by passing an `aria-label` prop.

```vue
<template>
<BarChart aria-label="Sales figures for the years 2022 to 2024. Sales in 2022: 987, Sales in 2023: 1209, Sales in 2024: 825." />
</template>
```

### `aria-describedby`

You can reference to a describing element such as a table which describes the data by using the `aria-describedby` property.

```vue
<template>
<BarChart aria-describedby="my-data-table" />
<table id="my-data-table">
<caption>Sales figures for the years 2022 to 2024.</caption>
<thead>
<tr>
<th>2022</th>
<th>2023</th>
<th>2024</th>
</tr>
</thead>
<tbody>
<tr>
<td>987</td>
<td>1209</td>
<td>825</td>
</tr>
</tbody>
</table>
</template>
```

### Fallback-Content

In case the Browser is not able to render the `canvas` element, you should consider providing fallback content by using the Slot of each component.

```vue
<template>
<BarChart>Chart couldn't be loaded.</BarChart>
</template>
```
20 changes: 20 additions & 0 deletions website/src/de/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
---
layout: home
hero:
name: 📈 vue-chartjs
tagline: ⚡ Einfache und schöne Diagramme mit Chart.js und Vue.js
actions:
- theme: brand
text: Get Started →
link: /guide/
features:
- icon: 🙌
title: Einfach
details: Einfach für beginner sowie fortgeschrittene
- icon: 💪
title: Erweiterbar
details: Simple to use, easy to extend
- icon: 💯
title: Mächtig
details: With the full power of chart.js 💯
---
13 changes: 13 additions & 0 deletions website/src/de/migration-guides/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
layout: doc
---

# Migration

Over the time `vue-chartjs` has changed a lot. As the web and frontend technology has changed.
To keep up with the speed of evolution we have iterated and changed a lot. For a smooth transition between version please check the migration guides.


- [v4 -> v5](/migration-guides/v5)
- [v3 -> v4](/migration-guides/v4)
- [vue-chart-3](/migration-guides/vue-chart-3)
170 changes: 170 additions & 0 deletions website/src/de/migration-guides/v4.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,170 @@
---
layout: doc
---
# Migration from v3 to v4

With v4, this library introduces a number of breaking changes. In order to improve performance, offer new features, and improve maintainability, it was necessary to break backwards compatibility, but we aimed to do so only when worth the benefit.

v4 is fully compatible with Chart.js v3.

## Tree-shaking

v4 of this library, [just like Chart.js v3](https://www.chartjs.org/docs/latest/getting-started/v3-migration.html#setup-and-installation), is tree-shakable. It means that you need to import and register the controllers, elements, scales, and plugins you want to use.

For a list of all the available items to import, see [Chart.js docs](https://www.chartjs.org/docs/latest/getting-started/integration.html#bundlers-webpack-rollup-etc).

v3:

```javascript
import { Bar } from 'vue-chartjs'
```

v4 — lazy way:

```javascript
import 'chart.js/auto';
import { Bar } from 'vue-chartjs'
```

v4 — tree-shakable way:

```javascript
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'

ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
```

Using the "lazy way" is okay to simplify the migration, but please consider using the tree-shakable way to decrease the bundle size.

Please note that typed chart components register their controllers by default, so you don't need to register them by yourself. For example, when using the Pie component, you don't need to register PieController explicitly.

```javascript
import { Pie } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, ArcElement, CategoryScale } from 'chart.js'

ChartJS.register(Title, Tooltip, Legend, ArcElement, CategoryScale)
```

## Changing the creation of Charts

In v3, you needed to import the component, and then either use extends or mixins and add it.

v3:

```javascript
// BarChart.js
import { Bar } from 'vue-chartjs'

export default {
extends: Bar,
mounted () {
// Overwriting base render method with actual data.
this.renderChart({
labels: ['January', 'February', 'March'],
datasets: [
{
label: 'GitHub Commits',
backgroundColor: '#f87979',
data: [40, 20, 12]
}
]
})
}
}
```

```vue
<template>
<BarChart />
</template>
<script>
import BarChart from 'path/to/component/BarChart'
export default {
name: 'DataPage',
components: { BarChart }
}
</script>
```

In v4, you need to import the component, pass props to it, and use Chart component as a standard Vue component.

```vue
<template>
<Bar :chart-data="chartData" />
</template>
<script>
// DataPage.vue
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
data() {
return {
chartData: {
labels: [ 'January', 'February', 'March'],
datasets: [
{
label: 'Data One',
backgroundColor: '#f87979',
data: [40, 20, 12]
}
]
}
}
}
}
</script>
```

## New reactivity system

v3 does not update or re-render the chart if new data is passed. You needed to use `reactiveProp` and `reactiveData` mixins for that.

v3:

```javascript
import { Line, mixins } from 'vue-chartjs'

export default {
extends: Line,
mixins: [mixins.reactiveProp],
props: ['chartData', 'options'],
mounted () {
this.renderChart(this.chartData, this.options)
}
}
```

v4 charts have data change watcher by default. v4 will update or re-render the chart if new data is passed. Mixins have been removed.

v4:

```vue
<template>
<Bar :chart-data="chartData" />
</template>
<script>
// DataPage.vue
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
computed: {
chartData() { return /* mutable chart data */ }
}
}
</script>
```
31 changes: 31 additions & 0 deletions website/src/de/migration-guides/v5.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Migration from v4 to v5

With v5, this library introduces a number of breaking changes

## ESM

### v5.0

Chart.js v4 and vue-chartjs v5 are [ESM-only packages](https://nodejs.org/api/esm.html). To use them in your project, it also should be ESM:

```json
// package.json
{
"type": "module"
}
```

If you are experiencing this problem with Jest, you should follow [this doc](https://jestjs.io/docs/ecmascript-modules) to enable ESM support. Or, we can recommend you migrate to [Vitest](https://vitest.dev/). Vitest has ESM support out of the box and [has almost the same API as Jest](https://vitest.dev/guide/migration.html#migrating-from-jest). [Here is our example of migration](https://github.com/reactchartjs/react-chartjs-2/commit/7f3ec96101d21e43cae8cbfe5e09a46a17cff1ef).


### v5.1

Chart.js v4.1 and vue-chartjs v5.1 have restored the CommonJS support.

## API changes

- `chartData` props were renamed to `data`
- `chartOptions` props were renamed to `options`
- unknown props will fall through to the canvas element.
- `generateChart` were refactored and renamed to `createTypedChart`
- Vue.js < 2.7 is no longer supported. If you want to use vue-chartjs with Vue < 2.7 you have to lock your version to 4.x.
51 changes: 51 additions & 0 deletions website/src/de/migration-guides/vue-chart-3.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@

# Migration from vue-chart-3

## Uninstall vue-chart-3

```bash
pnpm rm vue-chart-3
# or
yarn remove vue-chart-3
# or
npm uninstall vue-chart-3
```

## Install vue-chartjs

```bash
pnpm add vue-chartjs
# or
yarn add vue-chartjs
# or
npm i vue-chartjs
```

## Change component import path

For Vue 2.7 and Vue 3 projects:

```javascript
import { /* component */ } from 'vue-chartjs'
```

For Vue 2 (<2.7) projects:

```javascript
import { /* component */ } from 'vue-chartjs/legacy'
```

## Rename components

- BarChart to Bar
- DoughnutChart to Doughnut
- LineChart to Line
- PieChart to Pie
- PolarAreaChart to PolarArea
- RadarChart to Radar
- BubbleChart to Bubble
- ScatterChart to Scatter

## Rename props

- options to chartOptions
189 changes: 189 additions & 0 deletions website/src/guide/examples.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,189 @@

# Examples

## Chart with props

Your goal should be to create reusable chart components. For this purpose, you should utilize Vue.js props to pass in chart options and chart data. This way, the parent component itself does not hold an opinion about fetching data and is only for presentation.

```vue
<template>
<Bar :data="chartData" :options="chartOptions" />
</template>
<script>
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
props: {
chartData: {
type: Object,
required: true
},
chartOptions: {
type: Object,
default: () => {}
}
}
}
</script>
```

## Chart with local data

You can handle your chart data directly in your parent component.

```vue
<template>
<Bar :data="chartData" />
</template>
<script>
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
data() {
return {
chartData: {
labels: [ 'January', 'February', 'March'],
datasets: [
{
label: 'Data One',
backgroundColor: '#f87979',
data: [40, 20, 12]
}
]
}
}
}
}
</script>
```

## Chart with API data

A common pattern is to use an API to retrieve your data. However, there are some things to keep in mind. The most common problem is that you mount your chart component directly and pass in data from an asynchronous API call. The problem with this approach is that Chart.js tries to render your chart and access the chart data synchronously, so your chart mounts before the API data arrives.

To prevent this, a simple `v-if` is the best solution.

Create your chart component with a data prop and options prop, so we can pass in our data and options from a container component.

```vue
<template>
<div class="container">
<Bar v-if="loaded" :data="chartData" />
</div>
</template>
<script>
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
data: () => ({
loaded: false,
chartData: null
}),
async mounted () {
this.loaded = false
try {
const { userlist } = await fetch('/api/userlist')
this.chartdata = userlist
this.loaded = true
} catch (e) {
console.error(e)
}
}
}
</script>
```

## Chart with dynamic styles

You can set `responsive: true` and pass in a styles object which gets applied as inline styles to the outer `<div>`. This way, you can change the height and width of the outer container dynamically, which is not the default behaviour of Chart.js. It is best to use computed properties for this.

::: warning
You need to set `position: relative`
:::

```vue
<template>
<div>
<Bar :style="myStyles"/>
</div>
</template>
<script>
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
computed: {
myStyles () {
return {
height: `${/* mutable height */}px`,
position: 'relative'
}
}
}
}
</script>
```

## Custom / New Charts

Sometimes you need to extend the default Chart.js charts. There are a lot of [examples](http://www.chartjs.org/docs/latest/developers/charts.html) on how to extend and modify the default charts. Or, you can create your own chart type.

In `vue-chartjs`, you can do this pretty much the same way:

```js
// 1. Import Chart.js so you can use the global Chart object
import { Chart } from 'chart.js'
// 2. Import the `createTypedChart()` method to create the vue component.
import { createTypedChart } from 'vue-chartjs'
// 3. Import needed controller from Chart.js
import { LineController } from 'chart.js'

// 3. Extend one of the default charts
// http://www.chartjs.org/docs/latest/developers/charts.html
class LineWithLineController extends LineController { /* custom magic here */}

// 4. Generate the vue-chartjs component
// The first argument is the chart-id, the second the chart type, third is the custom controller
const CustomLine = createTypedChart('line', LineWithLineController)

// 5. Extend the CustomLine Component just like you do with the default vue-chartjs charts.

export default {
components: { CustomLine }
}
```

## Resources

Here are some resources, such as tutorials, on how to use `vue-chartjs`:

- [Using vue-chartjs with WordPress](https://medium.com/@apertureless/wordpress-vue-and-chart-js-6b61493e289f)
- [Create stunning Charts with Vue and Chart.js](https://hackernoon.com/creating-stunning-charts-with-vue-js-and-chart-js-28af584adc0a)
- [Let’s Build a Web App with Vue, Chart.js and an API Part I](https://hackernoon.com/lets-build-a-web-app-with-vue-chart-js-and-an-api-544eb81c4b44)
- [Let’s Build a Web App with Vue, Chart.js and an API Part II](https://hackernoon.com/lets-build-a-web-app-with-vue-chart-js-and-an-api-part-ii-39781b1d5acf)
- [Build a realtime chart with VueJS and Pusher](https://blog.pusher.com/build-realtime-chart-with-vuejs-pusher/)
189 changes: 0 additions & 189 deletions website/src/guide/index.md
Original file line number Diff line number Diff line change
@@ -208,192 +208,3 @@ In case the Browser is not able to render the `canvas` element, you should consi
<BarChart>Chart couldn't be loaded.</BarChart>
</template>
```

## Examples

### Chart with props

Your goal should be to create reusable chart components. For this purpose, you should utilize Vue.js props to pass in chart options and chart data. This way, the parent component itself does not hold an opinion about fetching data and is only for presentation.

```vue
<template>
<Bar :data="chartData" :options="chartOptions" />
</template>
<script>
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
props: {
chartData: {
type: Object,
required: true
},
chartOptions: {
type: Object,
default: () => {}
}
}
}
</script>
```

### Chart with local data

You can handle your chart data directly in your parent component.

```vue
<template>
<Bar :data="chartData" />
</template>
<script>
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
data() {
return {
chartData: {
labels: [ 'January', 'February', 'March'],
datasets: [
{
label: 'Data One',
backgroundColor: '#f87979',
data: [40, 20, 12]
}
]
}
}
}
}
</script>
```

### Chart with API data

A common pattern is to use an API to retrieve your data. However, there are some things to keep in mind. The most common problem is that you mount your chart component directly and pass in data from an asynchronous API call. The problem with this approach is that Chart.js tries to render your chart and access the chart data synchronously, so your chart mounts before the API data arrives.

To prevent this, a simple `v-if` is the best solution.

Create your chart component with a data prop and options prop, so we can pass in our data and options from a container component.

```vue
<template>
<div class="container">
<Bar v-if="loaded" :data="chartData" />
</div>
</template>
<script>
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
data: () => ({
loaded: false,
chartData: null
}),
async mounted () {
this.loaded = false
try {
const { userlist } = await fetch('/api/userlist')
this.chartdata = userlist
this.loaded = true
} catch (e) {
console.error(e)
}
}
}
</script>
```

### Chart with dynamic styles

You can set `responsive: true` and pass in a styles object which gets applied as inline styles to the outer `<div>`. This way, you can change the height and width of the outer container dynamically, which is not the default behaviour of Chart.js. It is best to use computed properties for this.

::: warning
You need to set `position: relative`
:::

```vue
<template>
<div>
<Bar :style="myStyles"/>
</div>
</template>
<script>
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
computed: {
myStyles () {
return {
height: `${/* mutable height */}px`,
position: 'relative'
}
}
}
}
</script>
```

### Custom / New Charts

Sometimes you need to extend the default Chart.js charts. There are a lot of [examples](http://www.chartjs.org/docs/latest/developers/charts.html) on how to extend and modify the default charts. Or, you can create your own chart type.

In `vue-chartjs`, you can do this pretty much the same way:

```js
// 1. Import Chart.js so you can use the global Chart object
import { Chart } from 'chart.js'
// 2. Import the `createTypedChart()` method to create the vue component.
import { createTypedChart } from 'vue-chartjs'
// 3. Import needed controller from Chart.js
import { LineController } from 'chart.js'

// 3. Extend one of the default charts
// http://www.chartjs.org/docs/latest/developers/charts.html
class LineWithLineController extends LineController { /* custom magic here */}

// 4. Generate the vue-chartjs component
// The first argument is the chart-id, the second the chart type, third is the custom controller
const CustomLine = createTypedChart('line', LineWithLineController)

// 5. Extend the CustomLine Component just like you do with the default vue-chartjs charts.

export default {
components: { CustomLine }
}
```

## Resources

Here are some resources, such as tutorials, on how to use `vue-chartjs`:

- [Using vue-chartjs with WordPress](https://medium.com/@apertureless/wordpress-vue-and-chart-js-6b61493e289f)
- [Create stunning Charts with Vue and Chart.js](https://hackernoon.com/creating-stunning-charts-with-vue-js-and-chart-js-28af584adc0a)
- [Let’s Build a Web App with Vue, Chart.js and an API Part I](https://hackernoon.com/lets-build-a-web-app-with-vue-chart-js-and-an-api-544eb81c4b44)
- [Let’s Build a Web App with Vue, Chart.js and an API Part II](https://hackernoon.com/lets-build-a-web-app-with-vue-chart-js-and-an-api-part-ii-39781b1d5acf)
- [Build a realtime chart with VueJS and Pusher](https://blog.pusher.com/build-realtime-chart-with-vuejs-pusher/)
26 changes: 16 additions & 10 deletions website/src/index.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,20 @@
---
home: true
heroImage: https://raw.githubusercontent.com/apertureless/vue-chartjs/main/website/src/images/vue-chartjs.png
actionText: Get Started →
actionLink: /guide/
layout: home
hero:
name: 📈 vue-chartjs
tagline: ⚡ Easy and beautiful charts with Chart.js and Vue.js
actions:
- theme: brand
text: Get Started →
link: /guide/
features:
- title: Easy
details: Easy for both beginners and pros 🙌
- title: Extendable
details: Simple to use, easy to extend 💪
- title: Powerful
- icon: 🙌
title: Easy
details: Easy for both beginners and pros
- icon: 💪
title: Extendable
details: Simple to use, easy to extend
- icon: 💯
title: Powerful
details: With the full power of chart.js 💯
footer: MIT Licensed | Copyright © 2018-present Jakub Juszczak
---
130 changes: 0 additions & 130 deletions website/src/ja/api/index.md

This file was deleted.

476 changes: 0 additions & 476 deletions website/src/ja/guide/index.md

This file was deleted.

14 changes: 0 additions & 14 deletions website/src/ja/index.md

This file was deleted.

130 changes: 0 additions & 130 deletions website/src/kr/api/index.md

This file was deleted.

498 changes: 0 additions & 498 deletions website/src/kr/guide/index.md

This file was deleted.

14 changes: 0 additions & 14 deletions website/src/kr/index.md

This file was deleted.

255 changes: 9 additions & 246 deletions website/src/migration-guides/index.md
Original file line number Diff line number Diff line change
@@ -1,250 +1,13 @@
## Migration from v4 to v5
---
layout: doc
---

With v5, this library introduces a number of breaking changes
# Migration

### ESM
Over the time `vue-chartjs` has changed a lot. As the web and frontend technology has changed.
To keep up with the speed of evolution we have iterated and changed a lot. For a smooth transition between version please check the migration guides.

#### v5.0

Chart.js v4 and vue-chartjs v5 are [ESM-only packages](https://nodejs.org/api/esm.html). To use them in your project, it also should be ESM:

```json
// package.json
{
"type": "module"
}
```

If you are experiencing this problem with Jest, you should follow [this doc](https://jestjs.io/docs/ecmascript-modules) to enable ESM support. Or, we can recommend you migrate to [Vitest](https://vitest.dev/). Vitest has ESM support out of the box and [has almost the same API as Jest](https://vitest.dev/guide/migration.html#migrating-from-jest). [Here is our example of migration](https://github.com/reactchartjs/react-chartjs-2/commit/7f3ec96101d21e43cae8cbfe5e09a46a17cff1ef).


#### v5.1

Chart.js v4.1 and vue-chartjs v5.1 have restored the CommonJS support.

### API changes

- `chartData` props were renamed to `data`
- `chartOptions` props were renamed to `options`
- unknown props will fall through to the canvas element.
- `generateChart` were refactored and renamed to `createTypedChart`
- Vue.js < 2.7 is no longer supported. If you want to use vue-chartjs with Vue < 2.7 you have to lock your version to 4.x.

## Migration from v3 to v4

With v4, this library introduces a number of breaking changes. In order to improve performance, offer new features, and improve maintainability, it was necessary to break backwards compatibility, but we aimed to do so only when worth the benefit.

v4 is fully compatible with Chart.js v3.

### Tree-shaking

v4 of this library, [just like Chart.js v3](https://www.chartjs.org/docs/latest/getting-started/v3-migration.html#setup-and-installation), is tree-shakable. It means that you need to import and register the controllers, elements, scales, and plugins you want to use.

For a list of all the available items to import, see [Chart.js docs](https://www.chartjs.org/docs/latest/getting-started/integration.html#bundlers-webpack-rollup-etc).

v3:

```javascript
import { Bar } from 'vue-chartjs'
```

v4 — lazy way:

```javascript
import 'chart.js/auto';
import { Bar } from 'vue-chartjs'
```

v4 — tree-shakable way:

```javascript
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'

ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
```

Using the "lazy way" is okay to simplify the migration, but please consider using the tree-shakable way to decrease the bundle size.

Please note that typed chart components register their controllers by default, so you don't need to register them by yourself. For example, when using the Pie component, you don't need to register PieController explicitly.

```javascript
import { Pie } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, ArcElement, CategoryScale } from 'chart.js'

ChartJS.register(Title, Tooltip, Legend, ArcElement, CategoryScale)
```

### Changing the creation of Charts

In v3, you needed to import the component, and then either use extends or mixins and add it.

v3:

```javascript
// BarChart.js
import { Bar } from 'vue-chartjs'

export default {
extends: Bar,
mounted () {
// Overwriting base render method with actual data.
this.renderChart({
labels: ['January', 'February', 'March'],
datasets: [
{
label: 'GitHub Commits',
backgroundColor: '#f87979',
data: [40, 20, 12]
}
]
})
}
}
```

```vue
<template>
<BarChart />
</template>
<script>
import BarChart from 'path/to/component/BarChart'
export default {
name: 'DataPage',
components: { BarChart }
}
</script>
```

In v4, you need to import the component, pass props to it, and use Chart component as a standard Vue component.

```vue
<template>
<Bar :chart-data="chartData" />
</template>
<script>
// DataPage.vue
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
data() {
return {
chartData: {
labels: [ 'January', 'February', 'March'],
datasets: [
{
label: 'Data One',
backgroundColor: '#f87979',
data: [40, 20, 12]
}
]
}
}
}
}
</script>
```

### New reactivity system

v3 does not update or re-render the chart if new data is passed. You needed to use `reactiveProp` and `reactiveData` mixins for that.

v3:

```javascript
import { Line, mixins } from 'vue-chartjs'

export default {
extends: Line,
mixins: [mixins.reactiveProp],
props: ['chartData', 'options'],
mounted () {
this.renderChart(this.chartData, this.options)
}
}
```

v4 charts have data change watcher by default. v4 will update or re-render the chart if new data is passed. Mixins have been removed.

v4:

```vue
<template>
<Bar :chart-data="chartData" />
</template>
<script>
// DataPage.vue
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
computed: {
chartData() { return /* mutable chart data */ }
}
}
</script>
```

## Migration from vue-chart-3

### Uninstall vue-chart-3

```bash
pnpm rm vue-chart-3
# or
yarn remove vue-chart-3
# or
npm uninstall vue-chart-3
```

### Install vue-chartjs

```bash
pnpm add vue-chartjs
# or
yarn add vue-chartjs
# or
npm i vue-chartjs
```

### Change component import path

For Vue 2.7 and Vue 3 projects:

```javascript
import { /* component */ } from 'vue-chartjs'
```

For Vue 2 (<2.7) projects:

```javascript
import { /* component */ } from 'vue-chartjs/legacy'
```

### Rename components

- BarChart to Bar
- DoughnutChart to Doughnut
- LineChart to Line
- PieChart to Pie
- PolarAreaChart to PolarArea
- RadarChart to Radar
- BubbleChart to Bubble
- ScatterChart to Scatter

### Rename props

- options to chartOptions
- [v4 -> v5](/migration-guides/v5)
- [v3 -> v4](/migration-guides/v4)
- [vue-chart-3](/migration-guides/vue-chart-3)
170 changes: 170 additions & 0 deletions website/src/migration-guides/v4.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,170 @@
---
layout: doc
---
# Migration from v3 to v4

With v4, this library introduces a number of breaking changes. In order to improve performance, offer new features, and improve maintainability, it was necessary to break backwards compatibility, but we aimed to do so only when worth the benefit.

v4 is fully compatible with Chart.js v3.

## Tree-shaking

v4 of this library, [just like Chart.js v3](https://www.chartjs.org/docs/latest/getting-started/v3-migration.html#setup-and-installation), is tree-shakable. It means that you need to import and register the controllers, elements, scales, and plugins you want to use.

For a list of all the available items to import, see [Chart.js docs](https://www.chartjs.org/docs/latest/getting-started/integration.html#bundlers-webpack-rollup-etc).

v3:

```javascript
import { Bar } from 'vue-chartjs'
```

v4 — lazy way:

```javascript
import 'chart.js/auto';
import { Bar } from 'vue-chartjs'
```

v4 — tree-shakable way:

```javascript
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'

ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
```

Using the "lazy way" is okay to simplify the migration, but please consider using the tree-shakable way to decrease the bundle size.

Please note that typed chart components register their controllers by default, so you don't need to register them by yourself. For example, when using the Pie component, you don't need to register PieController explicitly.

```javascript
import { Pie } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, ArcElement, CategoryScale } from 'chart.js'

ChartJS.register(Title, Tooltip, Legend, ArcElement, CategoryScale)
```

## Changing the creation of Charts

In v3, you needed to import the component, and then either use extends or mixins and add it.

v3:

```javascript
// BarChart.js
import { Bar } from 'vue-chartjs'

export default {
extends: Bar,
mounted () {
// Overwriting base render method with actual data.
this.renderChart({
labels: ['January', 'February', 'March'],
datasets: [
{
label: 'GitHub Commits',
backgroundColor: '#f87979',
data: [40, 20, 12]
}
]
})
}
}
```

```vue
<template>
<BarChart />
</template>
<script>
import BarChart from 'path/to/component/BarChart'
export default {
name: 'DataPage',
components: { BarChart }
}
</script>
```

In v4, you need to import the component, pass props to it, and use Chart component as a standard Vue component.

```vue
<template>
<Bar :chart-data="chartData" />
</template>
<script>
// DataPage.vue
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
data() {
return {
chartData: {
labels: [ 'January', 'February', 'March'],
datasets: [
{
label: 'Data One',
backgroundColor: '#f87979',
data: [40, 20, 12]
}
]
}
}
}
}
</script>
```

## New reactivity system

v3 does not update or re-render the chart if new data is passed. You needed to use `reactiveProp` and `reactiveData` mixins for that.

v3:

```javascript
import { Line, mixins } from 'vue-chartjs'

export default {
extends: Line,
mixins: [mixins.reactiveProp],
props: ['chartData', 'options'],
mounted () {
this.renderChart(this.chartData, this.options)
}
}
```

v4 charts have data change watcher by default. v4 will update or re-render the chart if new data is passed. Mixins have been removed.

v4:

```vue
<template>
<Bar :chart-data="chartData" />
</template>
<script>
// DataPage.vue
import { Bar } from 'vue-chartjs'
import { Chart as ChartJS, Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale } from 'chart.js'
ChartJS.register(Title, Tooltip, Legend, BarElement, CategoryScale, LinearScale)
export default {
name: 'BarChart',
components: { Bar },
computed: {
chartData() { return /* mutable chart data */ }
}
}
</script>
```
31 changes: 31 additions & 0 deletions website/src/migration-guides/v5.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Migration from v4 to v5

With v5, this library introduces a number of breaking changes

## ESM

### v5.0

Chart.js v4 and vue-chartjs v5 are [ESM-only packages](https://nodejs.org/api/esm.html). To use them in your project, it also should be ESM:

```json
// package.json
{
"type": "module"
}
```

If you are experiencing this problem with Jest, you should follow [this doc](https://jestjs.io/docs/ecmascript-modules) to enable ESM support. Or, we can recommend you migrate to [Vitest](https://vitest.dev/). Vitest has ESM support out of the box and [has almost the same API as Jest](https://vitest.dev/guide/migration.html#migrating-from-jest). [Here is our example of migration](https://github.com/reactchartjs/react-chartjs-2/commit/7f3ec96101d21e43cae8cbfe5e09a46a17cff1ef).


### v5.1

Chart.js v4.1 and vue-chartjs v5.1 have restored the CommonJS support.

## API changes

- `chartData` props were renamed to `data`
- `chartOptions` props were renamed to `options`
- unknown props will fall through to the canvas element.
- `generateChart` were refactored and renamed to `createTypedChart`
- Vue.js < 2.7 is no longer supported. If you want to use vue-chartjs with Vue < 2.7 you have to lock your version to 4.x.
51 changes: 51 additions & 0 deletions website/src/migration-guides/vue-chart-3.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@

# Migration from vue-chart-3

## Uninstall vue-chart-3

```bash
pnpm rm vue-chart-3
# or
yarn remove vue-chart-3
# or
npm uninstall vue-chart-3
```

## Install vue-chartjs

```bash
pnpm add vue-chartjs
# or
yarn add vue-chartjs
# or
npm i vue-chartjs
```

## Change component import path

For Vue 2.7 and Vue 3 projects:

```javascript
import { /* component */ } from 'vue-chartjs'
```

For Vue 2 (<2.7) projects:

```javascript
import { /* component */ } from 'vue-chartjs/legacy'
```

## Rename components

- BarChart to Bar
- DoughnutChart to Doughnut
- LineChart to Line
- PieChart to Pie
- PolarAreaChart to PolarArea
- RadarChart to Radar
- BubbleChart to Bubble
- ScatterChart to Scatter

## Rename props

- options to chartOptions
9 changes: 9 additions & 0 deletions website/src/pnpm-lock.yaml
128 changes: 0 additions & 128 deletions website/src/pt-br/api/index.md

This file was deleted.

482 changes: 0 additions & 482 deletions website/src/pt-br/guide/index.md

This file was deleted.

14 changes: 0 additions & 14 deletions website/src/pt-br/index.md

This file was deleted.

File renamed without changes
127 changes: 0 additions & 127 deletions website/src/ru/api/index.md

This file was deleted.

503 changes: 0 additions & 503 deletions website/src/ru/guide/index.md

This file was deleted.

14 changes: 0 additions & 14 deletions website/src/ru/index.md

This file was deleted.

128 changes: 0 additions & 128 deletions website/src/zh-cn/api/index.md

This file was deleted.

472 changes: 0 additions & 472 deletions website/src/zh-cn/guide/index.md

This file was deleted.

14 changes: 0 additions & 14 deletions website/src/zh-cn/index.md

This file was deleted.

0 comments on commit b43dd80

Please sign in to comment.