|
1 | | -# vue3-apexcharts |
2 | | -📊 Vue-3 component for ApexCharts |
| 1 | +<p align="center"><img src="https://apexcharts.com/media/vue-apexcharts.png"></p> |
| 2 | + |
| 3 | +<p align="center"> |
| 4 | + <a href="https://github.com/apexcharts/vue3-apexcharts/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-MIT-brightgreen.svg" alt="License"></a> |
| 5 | + <a href="https://travis-ci.com/apexcharts/vue3-apexcharts"><img src="https://api.travis-ci.com/apexcharts/vue3-apexcharts.svg?branch=master" alt="build" /></a> |
| 6 | + <a href="https://www.npmjs.com/package/vue3-apexcharts"><img src="https://img.shields.io/npm/v/vue3-apexcharts.svg" alt="ver"></a> |
| 7 | +</p> |
| 8 | + |
| 9 | +<p align="center"> |
| 10 | + <a href="https://twitter.com/intent/tweet?text=Vue3-ApexCharts%20A%20Vue.js%20Chart%20library%20built%20on%20ApexCharts.js&url=https://www.apexcharts.com&hashtags=javascript,charts,vue.js,vue,apexcharts"><img src="https://img.shields.io/twitter/url/http/shields.io.svg?style=social"> </a> |
| 11 | +</p> |
| 12 | + |
| 13 | +<p align="center">Vue 3 component for <a href="https://github.com/apexcharts/apexcharts.js">ApexCharts</a> to build interactive visualizations in vue.</p> |
| 14 | + |
| 15 | +<p align="center"><a href="https://apexcharts.com/vue-chart-demos/"><img src="https://apexcharts.com/media/apexcharts-banner.png"></a></p> |
| 16 | + |
| 17 | +## Download and Installation |
| 18 | + |
| 19 | +##### Installing via npm |
| 20 | + |
| 21 | +```bash |
| 22 | +npm install --save apexcharts |
| 23 | +npm install --save vue3-apexcharts |
| 24 | +``` |
| 25 | + |
| 26 | +If you're looking for Vue 2.x.x compatibile component, check-out <a href="https://github.com/apexcharts/vue-apexcharts">vue-apexcharts</a> |
| 27 | + |
| 28 | +## Usage |
| 29 | + |
| 30 | +```js |
| 31 | +import VueApexCharts from "vue3-apexcharts"; |
| 32 | +Vue.use(VueApexCharts); |
| 33 | + |
| 34 | +Vue.component("apexchart", VueApexCharts); |
| 35 | +``` |
| 36 | + |
| 37 | +To create a basic bar chart with minimal configuration, write as follows: |
| 38 | + |
| 39 | +```vue |
| 40 | +<template> |
| 41 | + <div> |
| 42 | + <apexchart |
| 43 | + width="500" |
| 44 | + type="bar" |
| 45 | + :options="chartOptions" |
| 46 | + :series="series" |
| 47 | + ></apexchart> |
| 48 | + </div> |
| 49 | +</template> |
| 50 | +``` |
| 51 | + |
| 52 | +```js |
| 53 | +export default { |
| 54 | + data: function () { |
| 55 | + return { |
| 56 | + chartOptions: { |
| 57 | + chart: { |
| 58 | + id: "vuechart-example", |
| 59 | + }, |
| 60 | + xaxis: { |
| 61 | + categories: [1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998], |
| 62 | + }, |
| 63 | + }, |
| 64 | + series: [ |
| 65 | + { |
| 66 | + name: "series-1", |
| 67 | + data: [30, 40, 35, 50, 49, 60, 70, 91], |
| 68 | + }, |
| 69 | + ], |
| 70 | + }; |
| 71 | + }, |
| 72 | +}; |
| 73 | +``` |
| 74 | + |
| 75 | +This will render the following chart |
| 76 | + |
| 77 | +<p><a href="https://apexcharts.com/javascript-chart-demos/column-charts/"><img src="https://apexcharts.com/media/first-bar-chart.svg"></a></p> |
| 78 | + |
| 79 | +### How do I update the chart? |
| 80 | + |
| 81 | +Simple! Just change the `series` or any `option` and it will automatically re-render the chart. <br/> Click on the below example to see this in action |
| 82 | + |
| 83 | +<p><a href="https://codesandbox.io/s/voyy36o7y"><img src="https://apexcharts.com/media/vue-chart-updation.gif"></a></p> |
| 84 | + |
| 85 | +```vue |
| 86 | +<template> |
| 87 | + <div class="app"> |
| 88 | + <apexchart |
| 89 | + width="550" |
| 90 | + type="bar" |
| 91 | + :options="chartOptions" |
| 92 | + :series="series" |
| 93 | + ></apexchart> |
| 94 | + <div> |
| 95 | + <button @click="updateChart">Update!</button> |
| 96 | + </div> |
| 97 | + </div> |
| 98 | +</template> |
| 99 | +``` |
| 100 | + |
| 101 | +```js |
| 102 | +export default { |
| 103 | + data: function () { |
| 104 | + return { |
| 105 | + chartOptions: { |
| 106 | + chart: { |
| 107 | + id: "vuechart-example", |
| 108 | + }, |
| 109 | + xaxis: { |
| 110 | + categories: [1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998], |
| 111 | + }, |
| 112 | + }, |
| 113 | + series: [ |
| 114 | + { |
| 115 | + name: "series-1", |
| 116 | + data: [30, 40, 45, 50, 49, 60, 70, 81], |
| 117 | + }, |
| 118 | + ], |
| 119 | + }; |
| 120 | + }, |
| 121 | + methods: { |
| 122 | + updateChart() { |
| 123 | + const max = 90; |
| 124 | + const min = 20; |
| 125 | + const newData = this.series[0].data.map(() => { |
| 126 | + return Math.floor(Math.random() * (max - min + 1)) + min; |
| 127 | + }); |
| 128 | + |
| 129 | + const colors = ["#008FFB", "#00E396", "#FEB019", "#FF4560", "#775DD0"]; |
| 130 | + |
| 131 | + // Make sure to update the whole options config and not just a single property to allow the Vue watch catch the change. |
| 132 | + this.chartOptions = { |
| 133 | + colors: [colors[Math.floor(Math.random() * colors.length)]], |
| 134 | + }; |
| 135 | + // In the same way, update the series option |
| 136 | + this.series = [ |
| 137 | + { |
| 138 | + data: newData, |
| 139 | + }, |
| 140 | + ]; |
| 141 | + }, |
| 142 | + }, |
| 143 | +}; |
| 144 | +``` |
| 145 | + |
| 146 | +**Important:** While updating the options, make sure to update the outermost property even when you need to update the nested property. |
| 147 | + |
| 148 | +✅ Do this |
| 149 | + |
| 150 | +```javascript |
| 151 | +this.chartOptions = { |
| 152 | + ...this.chartOptions, |
| 153 | + ...{ |
| 154 | + xaxis: { |
| 155 | + labels: { |
| 156 | + style: { |
| 157 | + colors: ["red"], |
| 158 | + }, |
| 159 | + }, |
| 160 | + }, |
| 161 | + }, |
| 162 | +}; |
| 163 | +``` |
| 164 | + |
| 165 | +❌ Not this |
| 166 | + |
| 167 | +```javascript |
| 168 | +this.chartOptions.xaxis = { |
| 169 | + labels: { |
| 170 | + style: { |
| 171 | + colors: ['red'] |
| 172 | + } |
| 173 | + } |
| 174 | +}} |
| 175 | +``` |
| 176 | + |
| 177 | +## Props |
| 178 | + |
| 179 | +| Prop | Type | Description | |
| 180 | +| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | |
| 181 | +| **series\*** | Array | The series is an array which accepts an object in the following format. To know more about the format of dataSeries, checkout [Series](https://apexcharts.com/docs/series/) docs on the website. | |
| 182 | +| **type\*** | String | `line`, `area`, `bar`, `pie`, `donut`, `scatter`, `bubble`, `heatmap`, `radialBar`, `candlestick` | |
| 183 | +| **width** | Number/String | Possible values for width can be `100%` or `400px` or `400` | |
| 184 | +| **height** | Number/String | Possible values for height can be `100%` or `300px` or `300` | |
| 185 | +| **options** | Object | The configuration object, see options on [API (Reference)](https://apexcharts.com/docs/options/chart/type/) | |
| 186 | + |
| 187 | +## Methods |
| 188 | + |
| 189 | +You don't actually need to call updateSeries() or updateOptions() manually. Changing the props will automatically update the chart. You only need to call these methods to update the chart forcefully. |
| 190 | + |
| 191 | +| Method | Description | |
| 192 | +| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | |
| 193 | +| <a href="https://apexcharts.com/docs/methods/#updateSeries">updateSeries</a> | Allows you to update the series array overriding the existing one | |
| 194 | +| <a href="https://apexcharts.com/docs/methods/#updateOptions">updateOptions</a> | Allows you to update the configuration object | |
| 195 | +| <a href="https://apexcharts.com/docs/methods/#toggleSeries">toggleSeries</a> | Allows you to toggle the visibility of series programatically. Useful when you have custom legend. | |
| 196 | +| <a href="https://apexcharts.com/docs/methods/#appendData">appendData</a> | Allows you to append new data to the series array. | |
| 197 | +| <a href="https://apexcharts.com/docs/methods/#addtext">addText</a> | The addText() method can be used to draw text after chart is rendered. | |
| 198 | +| <a href="https://apexcharts.com/docs/methods/#addxaxisannotation">addXaxisAnnotation</a> | Draw x-axis annotations after chart is rendered. | |
| 199 | +| <a href="https://apexcharts.com/docs/methods/#addyaxisannotation">addYaxisAnnotation</a> | Draw y-axis annotations after chart is rendered. | |
| 200 | +| <a href="https://apexcharts.com/docs/methods/#addpointannotation">addPointAnnotation</a> | Draw point (xy) annotations after chart is rendered. | |
| 201 | + |
| 202 | +How to call the methods mentioned above? |
| 203 | + |
| 204 | +```html |
| 205 | +<template> |
| 206 | + <div class="example"> |
| 207 | + <apexchart |
| 208 | + ref="demoChart" |
| 209 | + width="500" |
| 210 | + :options="chartOptions" |
| 211 | + :series="series" |
| 212 | + ></apexchart> |
| 213 | + </div> |
| 214 | +</template> |
| 215 | + |
| 216 | +<script> |
| 217 | + functionName: function() { |
| 218 | + this.$refs.demoChart.updateOptions({ colors: newColors }) |
| 219 | + }, |
| 220 | +</script> |
| 221 | +``` |
| 222 | + |
| 223 | +## How to call methods of ApexCharts without referencing the chart element? |
| 224 | + |
| 225 | +Sometimes, you may want to call methods of the core ApexCharts library from some other place, and you can do so on `this.$apexcharts` global variable directly. You need to target the chart by <code>chart.id</code> while calling this method |
| 226 | + |
| 227 | +Example |
| 228 | + |
| 229 | +```js |
| 230 | +this.$apexcharts.exec("vuechart-example", "updateSeries", [ |
| 231 | + { |
| 232 | + data: [40, 55, 65, 11, 23, 44, 54, 33], |
| 233 | + }, |
| 234 | +]); |
| 235 | +``` |
| 236 | + |
| 237 | +In the above method, `vuechart-example` is the ID of chart, `updateSeries` is the name of the method you want to call and the third parameter is the new Series you want to update. |
| 238 | + |
| 239 | +More info on the `.exec()` method can be found <a href="https://apexcharts.com/docs/methods/#exec">here</a> |
| 240 | + |
| 241 | +All other methods of ApexCharts can be called the same way. |
| 242 | + |
| 243 | +## What's included |
| 244 | + |
| 245 | +The repository includes the following files and directories. |
| 246 | + |
| 247 | +``` |
| 248 | +vue3-apexcharts/ |
| 249 | +├── dist/ |
| 250 | +│ └── vue-apexcharts.js |
| 251 | +└── src/ |
| 252 | + ├── ApexCharts.component.js |
| 253 | + ├── Utils.js |
| 254 | + └── index.js |
| 255 | +``` |
| 256 | + |
| 257 | +## Running the examples |
| 258 | + |
| 259 | +Basic Examples are included to show how to get started using ApexCharts with Vue easily. |
| 260 | + |
| 261 | +To run the examples, |
| 262 | + |
| 263 | +```bash |
| 264 | +cd example |
| 265 | +npm install |
| 266 | +npm run serve |
| 267 | +``` |
| 268 | + |
| 269 | +## Development |
| 270 | + |
| 271 | +#### Install dependencies |
| 272 | + |
| 273 | +```bash |
| 274 | +npm install |
| 275 | +``` |
| 276 | + |
| 277 | +#### Bundling |
| 278 | + |
| 279 | +```bash |
| 280 | +npm run build |
| 281 | +``` |
| 282 | + |
| 283 | +## Supporting ApexCharts |
| 284 | + |
| 285 | +ApexCharts is an open source project. <br /> You can help by becoming a sponsor on <a href="https://patreon.com/junedchhipa">Patreon</a> or doing a one time donation on <a href="https://paypal.me/junedchhipa">PayPal</a> <br /> |
| 286 | + |
| 287 | +<a href="https://patreon.com/junedchhipa"><img src="https://c5.patreon.com/external/logo/become_a_patron_button.png" alt="Become a Patron" /> </a> |
| 288 | + |
| 289 | +## License |
| 290 | + |
| 291 | +Vue3-ApexCharts is released under MIT license. You are free to use, modify and distribute this software, as long as the copyright header is left intact. |
0 commit comments