vue3-map-chart
Version:
Vue 3 component for rendering interactive SVG maps of the world, continents, and countries with dynamic data.
250 lines (186 loc) • 11.5 kB
Markdown
A Vue JS Component for displaying dynamic data on a world, continents and countries maps.
<p align="center">
<img width="600" alt="Demo GIF" src="https://github.com/noeGnh/vue3-map-chart/blob/master/demo.gif"/>
</p>
There are two versions of this package: `vue3-map-chart` and `vue3-map-chart-lite`. The `vue3-map-chart-lite` version loads maps dynamically from a CDN at runtime, so they are not bundled with your application. This keeps your build lightweight, ideal for users who only need a few maps or want to reduce initial load time. On the other hand, the full `vue3-map-chart` version includes all maps locally, offering faster access and offline support at the cost of a larger bundle size.
If you are using npm:
```sh
npm i vue3-map-chart
```
If you are using yarn:
```sh
yarn add vue3-map-chart
```
If you are using pnpm:
```sh
pnpm add vue3-map-chart
```
View the live demo [`here`](https://noegnh.github.io/vue3-map-chart/) and demo source code [`here`](https://github.com/noeGnh/vue3-map-chart/blob/master/packages/playground/).
You can add this package globally to your project:
```js
// main.js
import { createApp } from 'vue'
import App from './App.vue'
import Vue3MapChart from 'vue3-map-chart'
import 'vue3-map-chart/dist/style.css'
createApp(App).use(Vue3MapChart).mount('#app')
```
If needed rename component to use:
```js
createApp(App).use(Vue3MapChart, { name: 'MyMapChart' }).mount('#app') // use in template <MyMapChart />
```
If needed register some maps globally:
```js
import Vue3MapChart, { GermanyMap, JapanMap } from 'vue3-map-chart'
createApp(App).use(Vue3MapChart, { maps: { GermanyMap, 'Japan': JapanMap } }).mount('#app')
```
Map list can be found [`here`](https://github.com/noeGnh/vue3-map-chart/blob/master/packages/vue3-map-chart/map-list.txt)
Alternatively you can also import the components locally:
```js
<script setup>
import { MapChart, AfricaMap, AsiaMap, BrazilMap, EgyptMap, EuropeMap, NorthAmericaMap } from 'vue3-map-chart'
import 'vue3-map-chart/dist/style.css'
</script>
```
This component is most useful for creating heat maps of countries and their subdivisions. It colors each country or subdivision differently based on the props provided.
The component requires a prop of data to be passed to it, which is a JS object formatted like so.
```js
<script setup>
import { MapChart, WorldMap } from 'vue3-map-chart'
const data = {
DE: 95,
FR: 47,
GB: 10,
}
</script>
```
Or if for some reasons you want to customize each country color.
```js
<script setup>
import { MapChart, WorldMap } from 'vue3-map-chart'
const data = {
AU: {
color: 'blue',
value: 58,
},
NZ: {
color: '#339601',
value: 42,
},
ID: {
color: '#F7931E',
value: 62,
},
}
</script>
```
The key must be a valid [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1) or a [ISO 3166-2 subdivision code](https://en.wikipedia.org/wiki/ISO_3166-2). You can then use the component directly in your template and pass the map you want to display as a default slot.
```html
<template>
<MapChart :data="data">
<WorldMap />
</MapChart>
</template>
```
| Name | Type | Description | Default | Required |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------- | -------- |
| data | number / { value?: number, color?: string, legendLabel?: string } | See Usage Section above for details | undefined | Yes |
| baseColor | string | Color use for data representation | '#0782c5' | No |
| langCode | string | The language of countries name, subdivisions name is not supported | 'en' | No |
| width | number / string | Width of map | '100%' | No |
| height | number / string | Height of map | 500 | No |
| mapStyles | CSSProperties | Styles applied to map | {} | No |
| displayLegend | boolean | Display legend when mouse passes hover area on map | true | No |
| displayLegendWhenEmpty | boolean | Do not display legend when area value is empty | true | No |
| legendBgColor | string | Color of legend tooltip box | 'rgba(0, 0, 0, 0.5)' | No |
| legendTextColor | string | Color of legend text | '#fff' | No |
| legendDividerColor | string | Color of legend divider | 'rgba(255, 255, 255, 0.5)' | No |
| legendValuePrefix | string | Prefix added to value displayed on legend | '' | No |
| legendValueSuffix | string | Suffix added to value displayed on legend | '' | No |
| defaultStrokeColor | string | Default map stroke color | 'rgb(200, 200, 200)' | No |
| defaultStrokeHoverColor | string | Default map stroke hover color | 'rgb(200, 200, 200)' | No |
| defaultFillColor | string | Default map fill color | 'rgb(236, 236, 236)' | No |
| defaultFillHoverColor | string | Default map fill hover color | 'rgb(226, 226, 226)' | No |
| formatValueWithSiPrefix | boolean | Formats a number with a magnitude suffix | false | No |
| forceCursorPointer | boolean | Force the cursor to be in pointer mode even when the legend display is disabled | false | No |
| loaderColor | string | Color of the loader (Only for lite version) | '#3498db' | No |
| custom-map-svg | string | Raw SVG string (imported with `?raw` or defined inline). When provided, overrides the built-in maps. See [example](#example-using-a-custom-svg-map) | undefined | No |
| custom-map-labels | Record<string, string> | Maps SVG `id`s to display names for tooltips. Used with `custom-map-svg`. See [example](#example-using-a-custom-svg-map) | undefined | No |
## Slots
| Name | Description |
| ---- | ----------- |
| default | The map you want to display. |
| loader | Custom loader to display while the map is loading. (Only for lite version) |
## Events
- mapItemClick
- This event is fired when an map area is clicked.
- mapItemMouseout
- This event is fired when the mouse leaves a map area.
- mapItemMouseover
- This event is fired when the mouse passes over the top of an map area.
```js
<script setup>
import { MapChart, WorldMap } from 'vue3-map-chart'
const data = {
US: 43,
CA: 63,
GB: 20,
}
const onMapItemClick = (areaId, areaValue) => {
//
}
const onMapItemMouseout = (areaId, areaValue) => {
//
}
const onMapItemMouseover = (areaId, areaValue) => {
//
}
</script>
```
```html
<template>
<MapChart
:data="data"
@map-item-click="onMapItemClick"
@map-item-mouseover="onMapItemMouseover">
<WorldMap />
</MapChart>
</template>
```
```ts
// Import SVG as raw string using vite-plugin-svg-loader
import myMapSvg from './maps/my-map.svg?raw'
const labels = {
region1: 'North Zone',
region2: 'East District',
}
const data = {
region1: 150,
region2: 300,
}
```
```html
<template>
<MapChart
:custom-map-svg="myMapSvg"
:custom-map-labels="labels"
:data="data"
/>
</template>
```
> Each `code` in the `data` array must match an `id` attribute in the SVG’s `<path>` elements.
> Tooltips will display labels from `custom-map-labels` if available.
This package uses SVG maps from [`amCharts`](https://www.amcharts.com/)
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Detailed changes for each release are documented in the [release notes](https://github.com/noeGnh/vue3-map-chart/releases).
[](https://github.com/noeGnh/vue3-map-chart/blob/master/LICENSE)