<script lang="ts">
  import { mode } from "mode-watcher";
  import { BubbleMap, type MapGeoJson } from "kumo-svelte/components/chart";
  import { echarts } from "../chart-echarts";

  interface Props {
    geoJson: MapGeoJson | null;
  }

  let { geoJson }: Props = $props();
  let isDarkMode = $derived(mode.current === "dark");

  const data = [
    { city: "San Jose", requests: 1820000, longitude: -121.9, latitude: 37.3 },
    { city: "Ashburn", requests: 1240000, longitude: -77.5, latitude: 39.0 },
    { city: "London", requests: 980000, longitude: -0.1, latitude: 51.5 },
    { city: "Singapore", requests: 760000, longitude: 103.8, latitude: 1.3 },
    { city: "São Paulo", requests: 520000, longitude: -46.6, latitude: -23.5 },
  ];
</script>

{#if geoJson}
  <BubbleMap
    {echarts}
    {geoJson}
    {data}
    lng="longitude"
    lat="latitude"
    name="city"
    value="requests"
    {isDarkMode}
    valueFormat={(value) => `${(value / 1_000_000).toFixed(1)}M requests`}
  />
{/if}

Installation

BubbleMap requires echarts as a peer dependency. Consumers provide the GeoJSON feature collection; the component does not fetch map data or use map tiles.

pnpm add echarts

Import

import { MapChart, ScatterChart } from "echarts/charts";
import { GeoComponent, TooltipComponent } from "echarts/components";
import * as echarts from "echarts/core";
import { CanvasRenderer } from "echarts/renderers";

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

import { BubbleMap } from "kumo-svelte/components/chart";

Usage

<script lang="ts">
  import { BubbleMap } from "kumo-svelte/components/chart";
  import { echarts } from "./chart-echarts";

  const data = [{ city: "London", requests: 980000, longitude: -0.1, latitude: 51.5 }];
</script>

<BubbleMap
  {echarts}
  geoJson={world}
  {data}
  lng="longitude"
  lat="latitude"
  name="city"
  value="requests"
/>

Examples

Bubble Map

Plot raw rows by longitude and latitude. The value accessor controls proportional bubble size.

<script lang="ts">
  import { mode } from "mode-watcher";
  import { BubbleMap, type MapGeoJson } from "kumo-svelte/components/chart";
  import { echarts } from "../chart-echarts";

  interface Props {
    geoJson: MapGeoJson | null;
  }

  let { geoJson }: Props = $props();
  let isDarkMode = $derived(mode.current === "dark");

  const data = [
    { city: "San Jose", requests: 1820000, longitude: -121.9, latitude: 37.3 },
    { city: "Ashburn", requests: 1240000, longitude: -77.5, latitude: 39.0 },
    { city: "London", requests: 980000, longitude: -0.1, latitude: 51.5 },
    { city: "Singapore", requests: 760000, longitude: 103.8, latitude: 1.3 },
    { city: "São Paulo", requests: 520000, longitude: -46.6, latitude: -23.5 },
  ];
</script>

{#if geoJson}
  <BubbleMap
    {echarts}
    {geoJson}
    {data}
    lng="longitude"
    lat="latitude"
    name="city"
    value="requests"
    {isDarkMode}
    valueFormat={(value) => `${(value / 1_000_000).toFixed(1)}M requests`}
  />
{/if}

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}
  geoJson={map}
  {data}
  lng="longitude"
  lat="latitude"
  name="city"
  value="requests"
  tooltipFormatter={(row) =>
    `<strong>${row.city}</strong><br>${row.requests.toLocaleString()} requests`}
/>

API Reference

Prop	Type	Description
`echarts`	`typeof echarts`	Registered ECharts module instance.
`geoJson`	`MapGeoJson`	GeoJSON `FeatureCollection` used as the land base.
`data`	`T[]`	Raw data rows.
`lng` / `lat`	`MapAccessor<T, number>`	Longitude and latitude accessors.
`value`	`MapAccessor<T, number>`	Value accessor used for bubble sizing.
`name`	`MapAccessor<T, string>`	Optional label accessor used by the default tooltip.
`mapName`	`string`	Optional stable ECharts map registry name.
`minRadius` / `maxRadius`	`number`	Bubble radius range in pixels.
`bubbleSize`	`(value: number) => number`	Custom bubble radius function.
`bubbleColor`	`MapStyle<T, string>`	Bubble fill color or row callback.
`bubbleBorderColor`	`MapStyle<T, string>`	Bubble border color or row callback.
`bubbleBorderWidth`	`MapStyle<T, number>`	Bubble border width or row callback.
`center`	`[number, number]`	Optional map center as `[longitude, latitude]`.
`zoom`	`number`	Initial map zoom.
`roam`	`boolean`	Enables drag-to-pan and scroll-to-zoom.
`showTooltip`	`boolean`	Shows the default tooltip.
`valueFormat`	`(value: number) => string`	Formats values in the default tooltip.
`tooltipFormatter`	`(row: T) => string`	Custom tooltip HTML. Sanitize user-provided content before returning it.
`onBubbleHover`	`(row: T \\| undefined) => void`	Called when the pointer enters or leaves a bubble.
`onBubbleClick`	`(row: T) => void`	Called when a bubble is clicked.
`height`	`number`	Chart height in pixels.
`isDarkMode`	`boolean`	Uses the dark chart palette.
`ref`	`ECharts \\| null`	Bindable chart instance.