Skip to content
WunderUI

Map Chart

Pro

Map chart for values by place: a dot-matrix world map, or Europe or North America, with points sized by value.

Playground Map Charts

Workspaces by city

Active workspaces by city: 21 locations, workspaces from 290 to 1,860, highest in New York (1,860).
Active workspaces by city, data table
LocationWorkspaces
San Francisco1,240
New York1,860
Chicago690
Austin560
Toronto620
Vancouver330
Mexico City410
São Paulo730
London1,520
Berlin1,310
Paris880
Amsterdam720
Madrid510
Zurich450
Stockholm460
Warsaw380
Lagos290
Bangalore940
Singapore680
Tokyo1,070
Sydney540

Playground Regions

Workspaces by city

Active workspaces by city: 8 locations, workspaces from 380 to 1,520, highest in London (1,520).
Active workspaces by city, data table
LocationWorkspaces
London1,520
Berlin1,310
Paris880
Amsterdam720
Madrid510
Zurich450
Stockholm460
Warsaw380

Installation

Map Chart comes with WunderUI Core and Pro, in the package from your plan. See the plans.

The charts live in their own entry point: import the chart, its card and its hooks from @wunderui/react/charts, not from @wunderui/react.

Then import what you need:

tsx
import {
  MapChart,
  MapChartPoint,
  MapChartProps,
  MapChartZoom,
} from "@wunderui/react/charts"

States

Loading, empty and error keep the chart's size, so the card never jumps. Add a retry handler and the error state offers a Try again button.

Workspaces by city

Active workspaces by city: 21 locations, workspaces from 290 to 1,860, highest in New York (1,860).
Active workspaces by city, data table
LocationWorkspaces
San Francisco1,240
New York1,860
Chicago690
Austin560
Toronto620
Vancouver330
Mexico City410
São Paulo730
London1,520
Berlin1,310
Paris880
Amsterdam720
Madrid510
Zurich450
Stockholm460
Warsaw380
Lagos290
Bangalore940
Singapore680
Tokyo1,070
Sydney540

Anatomy

The parts the component is made of. Each one renders a you can target from CSS.

Workspaces by city

Active workspaces by city: 21 locations, workspaces from 290 to 1,860, highest in New York (1,860).
Active workspaces by city, data table
LocationWorkspaces
San Francisco1,240
New York1,860
Chicago690
Austin560
Toronto620
Vancouver330
Mexico City410
São Paulo730
London1,520
Berlin1,310
Paris880
Amsterdam720
Madrid510
Zurich450
Stockholm460
Warsaw380
Lagos290
Bangalore940
Singapore680
Tokyo1,070
Sydney540
  • data-slot="map-chart"

    Takes the locations (id, label, latitude, longitude, value), the section of the map (world, Europe or North America), a value formatter and label, and onPointClick. Points outside the section are left out.

  • data-slot="map-land"

    A dot matrix of the land in the border-control token, drawn from a coarse mask built into the library. About 110 dots across, 4.5 to 9 px apart.

  • data-slot="map-points"

    One circle per location in the first chart colour, its area growing with the value; larger points are drawn first so small ones stay on top. The active point gets a heavier ring.

  • data-slot="chart-plot"

    The focusable region. Arrow keys, Home and End walk the points in data order and the live region reads each one; Enter or Space calls onPointClick.

  • data-slot="chart-tooltip"

    The shared chart tooltip: the location and its value.

  • data-slot="chart-skeleton"
  • data-slot="map-point"Optional

Best practices

  • When to use

    Use a Map Chart when where something happens matters: customers, sessions or offices by city. To compare values, put a ranked list or a bar chart beside it.

  • Do

    Set valueLabel and valueFormatter, so the tooltip, the live region and the table read Workspaces 1,310 rather than Value 1.3k.

  • Do

    Pick the section that holds the points: zoom Europe when most points are in Europe, so they do not pile up.

  • Don’t

    Don't use it for exact comparisons; point areas are hard to compare. Show the numbers next to it.

  • Don’t

    Don't plot hundreds of points; above a few dozen they overlap. Group them by city or region first.

API reference

One table per part, in the order of the anatomy. Every part also takes the props of the Base UI part it wraps (such as , and ) and the native attributes of its element.

Takes the locations (id, label, latitude, longitude, value), the section of the map (world, Europe or North America), a value formatter and label, and onPointClick. Points outside the section are left out.

PropTypeDefaultDescription
data requiredreadonly MapChartPoint[]—
activeIndexnumber | null—
animateboolean—
animationKeystring | number—
defaultActiveIndexnumber | null—
descriptionstring—
emptyDescriptionstring—
emptyTitlestring—
errorDescriptionstring—
errorTitlestring—
heightnumber360Height of the plot frame in px. Default 280 (Figma small card plot).
hiddenSeriesreadonly string[]—Labels of rows switched off in the legend: drawn faded.
labelstring—Accessible name, e.g. the card title.
onActiveIndexChange(index) => void—
onPointClick(point, index) => void—A click on a point, or Enter / Space while the keyboard is on it.
onRetry() => void—
state"ready" | "loading" | "empty" | "error"—
tooltipboolean—
valueFormatterChartValueFormatter—Formats the value in the tooltip, the live region and the data table. Default: compact (1.2k).
valueLabelstring"Value"Name of the value in the tooltip and the table header, e.g. "Sessions". Default "Value".
widthnumber—
zoom"world" | "europe" | "north-america""world"The section of the map. Points outside it are left out (also from the data table). Default .

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("map-chart")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.