Phi / Maps

Maps

@dicehub/phiv1.0.0-beta.1

<script setup lang="ts">
const cloudflareLocations = [
  { city: "San Francisco", iata: "SFO", lat: 37.77, lon: -122.42 },
  { city: "London", iata: "LHR", lat: 51.51, lon: -0.13 },
  { city: "Singapore", iata: "SIN", lat: 1.35, lon: 103.82 },
  // ...more locations
];
</script>

<template>
  <BubbleMap
    :echarts="echarts"
    :geo-json="geoJson"
    :data="cloudflareLocations"
    lng="lon"
    lat="lat"
    name="city"
    :value="() => 1"
    bubble-color="#F6821F"
    :min-radius="8"
    :max-radius="8"
    :tooltip-formatter="(row) =>
      '<strong>' + row.city + '</strong> ' + row.iata
    "
  />
</template>

Installation

Map charts require ECharts. Consumers provide GeoJSON; components do not fetch map data or tiles.

pnpm add echarts

Imports

import { BubbleMap, ChoroplethMap, type MapGeoJson } from "@dicehub/phi/components/chart";

Usage

BubbleMap

<script setup lang="ts">
import { BubbleMap, type MapGeoJson } from "@dicehub/phi/components/chart";
import * as echarts from "echarts/core";
import { MapChart, ScatterChart } from "echarts/charts";
import { GeoComponent, TooltipComponent } from "echarts/components";
import { CanvasRenderer } from "echarts/renderers";

echarts.use([CanvasRenderer, GeoComponent, MapChart, ScatterChart, TooltipComponent]);

const geoJson = world as MapGeoJson;

const colos = [
  { city: "San Francisco", lat: 37.77, lon: -122.42, requests: 1200 },
  { city: "London", lat: 51.5, lon: -0.12, requests: 1500 },
];
</script>

<template>
  <BubbleMap
    :echarts="echarts"
    :geo-json="geoJson"
    :data="colos"
    lng="lon"
    lat="lat"
    name="city"
    value="requests"
  />
</template>

ChoroplethMap

<script setup lang="ts">
import { ChoroplethMap, type MapGeoJson } from "@dicehub/phi/components/chart";
import * as echarts from "echarts/core";
import { MapChart } from "echarts/charts";
import { TooltipComponent, VisualMapComponent } from "echarts/components";
import { CanvasRenderer } from "echarts/renderers";

echarts.use([CanvasRenderer, MapChart, TooltipComponent, VisualMapComponent]);

const geoJson = world as MapGeoJson;

const countries = [
  { country: "United States of America", requests: 4200 },
  { country: "Germany", requests: 3100 },
  { country: "Japan", requests: 2500 },
];
</script>

<template>
  <ChoroplethMap
    :echarts="echarts"
    :geo-json="geoJson"
    :data="countries"
    name="country"
    value="requests"
  />
</template>

Examples

Bubble Map

Plot raw rows by longitude and latitude.

<BubbleMap
  :echarts="echarts"
  :geo-json="geoJson"
  :data="colos"
  lng="lon"
  lat="lat"
  name="city"
  value="requests"
  :min-radius="8"
/>

Choropleth Map

Join rows to GeoJSON regions and shade each region by value.

<ChoroplethMap
  :echarts="echarts"
  :geo-json="geoJson"
  :data="countries"
  name="country"
  value="requests"
/>

Custom Tooltips

Provide tooltipFormatter when the default name/value tooltip is not enough. The formatter returns HTML rendered by ECharts, so escape user-provided values.

<BubbleMap
  :echarts="echarts"
  :geo-json="geoJson"
  :data="colos"
  lng="lon"
  lat="lat"
  name="city"
  value="requests"
  :tooltip-formatter="(row) =>
    '<strong>' + row.city + '</strong><br />' + row.requests.toLocaleString()
  "
/>

API Reference

BubbleMap

Prop	Type	Default	Description
`echarts`	`typeof echarts`	`-`	ECharts core instance with map, scatter, geo, tooltip, and renderer modules registered.
`geoJson`	`MapGeoJson`	`-`	GeoJSON feature collection used as the map base.
`mapName`	`string`	`-`	Optional stable ECharts map registry name.
`data`	`T[]`	`-`	Rows rendered as proportional bubbles.
`lng`	`MapAccessor<T, number>`	`-`	Longitude accessor.
`lat`	`MapAccessor<T, number>`	`-`	Latitude accessor.
`value`	`MapAccessor<T, number>`	`-`	Numeric accessor used for bubble size.
`name`	`MapAccessor<T, string>`	`-`	Optional label accessor used by the default tooltip.
`minRadius`	`number`	`6`	Smallest bubble radius in pixels.
`maxRadius`	`number`	`26`	Largest bubble radius in pixels.
`bubbleSize`	`(value: number) => number`	`-`	Explicit bubble radius function. Overrides minRadius and maxRadius scaling.
`bubbleColor`	`MapStyle<T, string>`	`palette bubble`	Bubble fill color as a constant or row function.
`bubbleBorderColor`	`MapStyle<T, string>`	`"transparent"`	Bubble border color as a constant or row function.
`bubbleBorderWidth`	`MapStyle<T, number>`	`0`	Bubble border width as a constant or row function.
`center`	`[number, number]`	`-`	Map center as longitude and latitude.
`zoom`	`number`	`1.25`	Zoom level applied to the auto-fit scale.
`roam`	`boolean`	`false`	Enables drag-to-pan and scroll-to-zoom.
`projection`	`MapProjection \| null`	`Mercator`	Geographic projection. Pass null for raw longitude/latitude plotting.
`showTooltip`	`boolean`	`true`	Controls map tooltip visibility.
`valueFormat`	`(value: number) => string`	`toLocaleString()`	Formats values in the default tooltip.
`tooltipFormatter`	`(row: T) => string`	`-`	Optional trusted HTML tooltip formatter.
`onBubbleHover`	`(row: T \| undefined) => void`	`-`	Called as the pointer enters or leaves a bubble.
`onBubbleClick`	`(row: T) => void`	`-`	Called when a bubble is clicked.
`aspectRatio`	`number \| string`	`projected map ratio`	Responsive container ratio. Ignored when height is set.
`height`	`number`	`-`	Fixed chart height in pixels. Overrides aspectRatio.
`className`	`string`	`-`	Optional class passed to the chart element.
`isDarkMode`	`boolean`	`false`	Initializes ECharts with dark mode and dark map colors.

ChoroplethMap

Prop	Type	Default	Description
`echarts`	`typeof echarts`	`-`	ECharts core instance with map, visual map, tooltip, and renderer modules registered.
`geoJson`	`MapGeoJson`	`-`	GeoJSON feature collection whose regions are shaded by value.
`mapName`	`string`	`-`	Optional stable ECharts map registry name.
`data`	`T[]`	`-`	Rows joined to GeoJSON regions.
`name`	`MapAccessor<T, string>`	`-`	Region-key accessor matched against the configured GeoJSON name property.
`value`	`MapAccessor<T, number>`	`-`	Numeric accessor used for the region color scale.
`nameProperty`	`string`	`"name"`	GeoJSON feature property used for region joins.
`colorRange`	`string[]`	`sequential blues`	Continuous color ramp from low to high values.
`min`	`number`	`data min`	Lower bound of the continuous color scale.
`max`	`number`	`data max`	Upper bound of the continuous color scale.
`noDataColor`	`string`	`map area color`	Fill color for regions without matching data.
`showLegend`	`boolean`	`false`	Shows the continuous visual map legend.
`showTooltip`	`boolean`	`true`	Controls region tooltip visibility.
`valueFormat`	`(value: number) => string`	`toLocaleString()`	Formats values in the default tooltip.
`tooltipFormatter`	`(row: T) => string`	`-`	Optional trusted HTML tooltip formatter.
`onRegionHover`	`(row: T \| undefined) => void`	`-`	Called as the pointer enters or leaves a matched region.
`onRegionClick`	`(row: T) => void`	`-`	Called when a matched region is clicked.
`center`	`[number, number]`	`-`	Map center as longitude and latitude.
`zoom`	`number`	`1.25`	Zoom level applied to the map layout.
`roam`	`boolean`	`false`	Enables drag-to-pan and scroll-to-zoom.
`projection`	`MapProjection \| null`	`Mercator`	Geographic projection. Pass null for raw longitude/latitude plotting.
`aspectRatio`	`number \| string`	`projected map ratio`	Responsive container ratio. Ignored when height is set.
`height`	`number`	`-`	Fixed chart height in pixels. Overrides aspectRatio.
`className`	`string`	`-`	Optional class passed to the chart element.
`isDarkMode`	`boolean`	`false`	Initializes ECharts with dark mode and dark map colors.