Vue 3 Map Chart

A Vue JS Component for displaying dynamic data on a world, continents and countries maps.

Installation

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:

npm i vue3-map-chart # or: npm i vue3-map-chart-lite

If you are using yarn:

yarn add vue3-map-chart # or: yarn add vue3-map-chart-lite

If you are using pnpm:

pnpm add vue3-map-chart # or: pnpm add vue3-map-chart-lite

Demo

View the live demo here and demo source code here.

Usage

You can add this package globally to your project:

// main.js
import { createApp } from 'vue'
import Vue3MapChart from 'vue3-map-chart'
import 'vue3-map-chart/dist/style.css'

import App from './App.vue'

createApp(App).use(Vue3MapChart).mount('#app')

If needed rename component to use:

createApp(App).use(Vue3MapChart, { name: 'MyMapChart' }).mount('#app') // use in template <MyMapChart />

If needed register some maps globally:

import Vue3MapChart, { GermanyMap, JapanMap } from 'vue3-map-chart'

createApp(App)
  .use(Vue3MapChart, { maps: { GermanyMap, Japan: JapanMap } })
  .mount('#app')

Map list can be found here

Alternatively you can also import the components locally:

<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.

<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.

<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 or a ISO 3166-2 subdivision code. You can then use the component directly in your template and pass the map you want to display as a default slot.

<template>
  <MapChart :data="data">
    <WorldMap />
  </MapChart>
</template>

Props

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
areaNameOnMap	'none' / 'all' / 'data-only'	Display area name on map	'none'	No
areaNameOnMapSize	number	Font size of area name on map	12	No
areaNameOnMapColor	string	Color of area name on map	'#ffffff'	No
areaNameOnMapBgColor.	string	Background color of area name on map	'rgba(0, 0, 0, 0.6)'	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	undefined	No
custom-map-labels	Record<string, string>	Maps SVG ids to display names for tooltips. Used with custom-map-svg. See example	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.

<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>

<template>
  <MapChart
    :data="data"
    @map-item-click="onMapItemClick"
    @map-item-mouseover="onMapItemMouseover">
    <WorldMap />
  </MapChart>
</template>

Example: Using a custom SVG map

// 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,
}

<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.

Credits

This package uses SVG maps from amCharts

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Changelog

Detailed changes for each release are documented in the release notes.

License