# Map Chart

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

- Category: Charts
- Page: https://wunderui.com/components/map-chart
- Tier: Core and Pro

## Install

Map Chart ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

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

## Anatomy

- `MapChart`: 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.
- `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.
- `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.
- `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.
- `Tooltip`: The shared chart tooltip: the location and its value.
- `Chart Skeleton`
- `Map Point`

## 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.
- 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 plot hundreds of points; above a few dozen they overlap. Group them by city or region first.

## API reference

### MapChart

| Prop | Type | Default | Description |
|---|---|---|---|
| data* | readonly MapChartPoint[] |  |  |
| activeIndex | number \| null |  |  |
| animate | boolean |  |  |
| animationKey | string \| number |  |  |
| className | string |  |  |
| defaultActiveIndex | number \| null |  |  |
| description | string |  |  |
| emptyDescription | string |  |  |
| emptyTitle | string |  |  |
| errorDescription | string |  |  |
| errorTitle | string |  |  |
| height | number | 360 | Height of the plot frame in px. Default 280 (Figma small card plot). |
| hiddenSeries | readonly string[] |  | Labels of rows switched off in the legend: drawn faded. |
| label | string |  | Accessible name, e.g. the card title. |
| onActiveIndexChange | (index: number \| null) => void |  |  |
| onPointClick | (point: MapChartPoint, index: number) => void |  | A click on a point, or Enter / Space while the keyboard is on it. |
| onRetry | () => void |  |  |
| state | "ready" \| "loading" \| "empty" \| "error" |  |  |
| tooltip | boolean |  |  |
| valueFormatter | ChartValueFormatter |  | Formats the value in the tooltip, the live region and the data table. Default: compact (1.2k). |
| valueLabel | string | "Value" | Name of the value in the tooltip and the table header, e.g. "Sessions". Default "Value". |
| width | number |  |  |
| zoom | "world" \| "europe" \| "north-america" | "world" | The section of the map. Points outside it are left out (also from the data table). Default `world`. |

## Examples

### States

## In context

### Workspaces by City

Europe up close; a click on a city shows its numbers beside the map.

## For AI agents

`get_component("map-chart")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
