Bubble map

Installation

The command adds the example above to components/charts/ and, the first time, the chart kit to components/ui/charts/. Both are source files in your project from then on: read them, change them, delete what you don't use.

Usage

Each row needs a longitude, a latitude and a value, plus a name for the tooltip. The land is worldCountries, 177 countries as GeoJSON, installed in components/charts/data/ with any example that uses it.

<script setup lang="ts">
import { worldCountries } from "@/components/charts/data/world-countries";
import {
  BubbleMapBubbles,
  BubbleMapChart,
  BubbleMapLand,
  BubbleMapTooltip,
} from "@/components/ui/charts";

const cities = [
  { latitude: 40.71, longitude: -74.01, name: "New York", users: 184_200 },
  { latitude: 51.51, longitude: -0.13, name: "London", users: 158_700 },
  { latitude: 35.68, longitude: 139.69, name: "Tokyo", users: 119_600 },
  { latitude: -23.55, longitude: -46.63, name: "São Paulo", users: 71_200 },
];
</script>

<template>
  <BubbleMapChart
    ariaLabel="Active users by city"
    :data="cities"
    :geography="worldCountries"
  >
    <BubbleMapLand />
    <BubbleMapBubbles data-key="users" />
    <BubbleMapTooltip value-label="Active users" />
  </BubbleMapChart>
</template>

Anatomy

The layers stack in a fixed order: the world's outline, the land, the graticule, then the bubbles on top. Leave a part out and it isn't drawn.

<BubbleMapChart :data="cities" :geography="worldCountries">
  <BubbleMapGraticule />
  <BubbleMapLand />
  <BubbleMapBubbles data-key="users" />
  <BubbleMapTooltip value-label="Active users" />
  <BubbleMapLegend title="Active users" />
</BubbleMapChart>

• BubbleMapChart: Holds the places, the countries and the projection every layer shares.
• BubbleMapGraticule: Lines of longitude and latitude every 20°, and the world's outline.
• BubbleMapLand: The countries from geography.
• BubbleMapBubbles: A circle per row, its area set by dataKey.
• BubbleMapTooltip: The hovered place's name and value.
• BubbleMapLegend: Three reference sizes and, with colorKey, the categories.

Sizing

A bubble's area follows its value, so a city with four times the users gets twice the radius. maxRadius (22 px) is the largest value's size and minRadius (2 px) keeps small ones visible.

Big bubbles are drawn first, so a small one is never hidden under a big one. The pointer picks the smallest bubble it's inside.

Categories

Set colorKey to a field and each distinct value takes the next chart color, in order of appearance. <BubbleMapLegend> then shows the sizes and the categories side by side.

Without colorKey, color sets one fill for every bubble and fillOpacity (0.65) how much of the map shows through.

Regions and projections

By default the whole world fills the plot. fit="data" zooms to your places, with room for the largest bubble, and fit="geography" fits the features you pass. Countries past the edge are clipped.

projection is "equal-earth" (the default), "natural-earth", "mercator" or "orthographic". :rotate="[-10, 0]" turns the world so 10° east sits in the middle.

Customization

The kit is in your project, in components/ui/charts/: your framework's components over a shared core/. Change a default there and every chart picks it up.

class goes on the chart's container, so size and spacing are utility classes.

geography takes any GeoJSON feature collection, so you can swap the world for a country's states or your own sales regions. <BubbleMapLand> styles it with fill, stroke and strokeWidth.

content on <BubbleMapTooltip> gets the hovered row as bubble, so any field you keep on the row can go in the panel.

<BubbleMapTooltip>
  <template #content="{ bubble }">
    <div class="px-3 py-2 text-sm">
      <div class="font-medium">{{ String(bubble.name) }}</div>
      <div class="text-muted-foreground">
        {{ Number(bubble.users).toLocaleString() }} active users
      </div>
    </div>
  </template>
</BubbleMapTooltip>

Where a part renders content of its own, you pass it in. In Vue:

• BubbleMapTooltip: <template #content="{ bubble, index }">

Loading state

With status="loading" the land stays and skeleton bubbles of different sizes shimmer on it. The pointer is ignored until "ready", when they fade out and the real bubbles grow in.

loadingLabel puts a short line of text over the map.

Animation

The land fades in over 500 ms, then the bubbles grow from their centers, largest first, the stagger spread over animationDuration (900 ms).

Change revealSignature to play it again. :animate="false" and reduced motion both draw the map at rest.

Theming

Every color in the kit is one of your theme's tokens or a mix of them, except --chart-positive, a fixed green. A preset or the .dark class restyles the chart, and overriding a token in your CSS changes it everywhere.

Bubbles default to --chart-1, and categories take --chart-1 to --chart-5 in order. The land is your theme's --muted, its borders --chart-background so they match the card.

:root {
  --chart-background: var(--background);
  --chart-tooltip-background: var(--card);
}

Accessibility

The map is announced as an image named by ariaLabel ("Bubble map" by default). Name the measure and the period there, and the biggest places in ariaDescription.

The land never takes focus. Arrow keys move through the bubbles from left to right across the map, each showing its tooltip.

API reference

Vue takes the same props as React, in camelCase or kebab-case, with class for className. Render props are scoped slots (#content), and callbacks such as onHoverChange can be written as listeners (@hover-change).

BubbleMapChart

BubbleMapBubbles

BubbleMapLand

BubbleMapGraticule

BubbleMapTooltip

BubbleMapLegend