@kong-ui-public/analytics-geo-map

@kong-ui-public/analytics-geo-map

This Vue component provides a geographical map visualization based on maplibre-gl and displays country metrics using color-coded layers. It supports dynamic updates to country metrics and allows focusing on specific countries. Renders provided GeoJSON data into a choropleth style map.

• Features
• Requirements
• Usage
  • Install
  • Color mode (light/dark theme)
  • Props
  • Example

Features

• Interactive geographical map visualization using maplibre-gl.
• Color-coded countries based on provided metrics.
• Tooltips showing country names and their corresponding metrics.
• Ability to focus on specific countries with customizable bounds.
• Dynamic updates to country metrics and map features.

Requirements

• vue must be initialized in the host application.
• maplibre-gl must be added as a dependency in the host application. See here
• GeoJSON Data provided must include property "iso_a2" for each country Feature in order for this component to function properly. See here for a useful tool for generating GeoJSON country vector maps.

Usage

Install

First, ensure you have maplibre-gl installed:

npm install maplibre-gl
npm install @kong-ui-public/analytics-geo-map

Color mode (light/dark theme)

The map fills countries and water with design token colors, because maplibre-gl paint properties require literal color values rather than var(--kui-*), the component reads those tokens off the document.

To keep the map in step with the host's theme, provide a ComputedRef<'light' | 'dark'> under the app:konnectColorMode injection key. The component resolves its colors whenever the value changes.

// In the host application (e.g. within your root component's setup)
import { computed, provide } from 'vue'

// `isDarkMode` is however your app tracks its current theme
const colorMode = computed<'light' | 'dark'>(() => (isDarkMode.value ? 'dark' : 'light'))

provide('app:konnectColorMode', colorMode)

Props

countryMetrics

• type: Object (Record<string, number>)
• required: true
• description: An object mapping country codes to metric values. These metrics determine the color of each country on the map.

metricUnit

• type: String (MetricUnits)
• required: true
• description: Unit of measurement for the metrics displayed in the tooltips.

metric

• type: String (ExploreAggregations)
• required: true
• description: Metric aggregations for the data displayed on the map.

withLegend

• type: Boolean
• required: false
• default: true
• description: Whether to display a legend on the map.

showTooltipValue

• type: Boolean
• required: false
• default: true
• description: Display value in the tooltip.

fitToCountry

• type: String (CountryISOA2)
• required: false
• default: null
• description: Country code to zoom in on.

bounds

• type: Object (LngLatBoundsLike)
• required: false
• default: null
• description: Longitudinal/Latitudinal bounds to initially fit the map to.

Example

<template>
  <AnalyticsGeoMap
    :countryMetrics="countryMetrics"
    :geoJsonData="geoJsonData"
    :fitToCountry="'US'"
    metricUnit="%"
  />

  <!-- bounds to europe -->
  <AnalyticsGeoMap
    :countryMetrics="countryMetrics"
    :geoJsonData="geoJsonData"
    :bounds="[
      [-10, 35],
      [65, 72]
    ]"
    metricUnit="%"
  />
</template>

<script setup>
import { ref } from 'vue'
import AnalyticsGeoMap from '@kong-ui-public/analytics-geo-map'
import geoJsonData from './path-to-geojson-data.json'

const countryMetrics = ref({
  US: 75,
  CA: 50,
  MX: 25,
  // Other countries
})
</script>