# Map explorer

> A choropleth of US states or world countries with zoom, search, a ranked list and metric switching.

Block · Pro · https://lodeui.com/blocks/map-explorer

## When to use

- Sales, users or usage that differ by region.
- Spotting where to focus: the best and worst places at a glance.

## When not to use

- Comparing exact values between a handful of places: a bar chart is clearer.
- Values that just follow population: show per-person rates instead.

## Installation

```bash
npx shadcn@latest add @lode/map-explorer
```

Pro: needs a Lode API key and the `@lode` registry in components.json. See https://lodeui.com/docs/cli.

npm dependencies: motion, lucide-react, d3-geo, topojson-client, us-atlas, world-atlas

## Usage

```tsx title="example.tsx"
import { MapExplorer } from "@/components/blocks/map-explorer";

export default function Page() {
  return (
    <main className="mx-auto max-w-6xl p-6">
      <MapExplorer />
    </main>
  );
}
```

## API reference

### MapExplorer

A choropleth of US states or world countries: switch metric, click a place to fly in, and browse a ranked, searchable list that stays in sync with the map. Also the default export. No props: sample data sits at the top of the file, ready to swap for your own.

No props.

## Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Reach the metric and region toggles, zoom buttons, search and list |
| Enter | Select a place in the list and fly to it |
| Escape | Clear the selection and zoom out |

## Accessibility

- The map has a text summary; every value is in the ranked list, which is the keyboard route.
- List items are buttons with aria-pressed for the selected place.

## Motion

- The view flies to a place on a spring; colours fade when the metric changes.
- With reduced motion the view jumps instead.

## Responsive behavior

- The list moves below the map under 768px; the map keeps its aspect ratio.

## Performance

- Map shapes load only when a region is first shown (about 85 KB for US states, 110 KB for the world).
- Sample data is plain arrays at the top of the file. Replace them with your API data and keep the shapes.

## Notes for AI

- Replace sample() with a lookup by state or country name (or its id).
- Colours are quantiles, so each shade covers about the same number of places.

## Related

- [Heatmap](https://lodeui.com/components/heatmap) — A color-scaled grid with row and column tracking, for cohorts and schedules.
- [Cohort retention](https://lodeui.com/blocks/cohort-retention) — Retention by signup month as a heatmap, with segments.
- [Treemap](https://lodeui.com/components/treemap) — Squarified rectangles sized by value, for revenue mix, storage and market caps.