Migrate from react-simple-maps

@d3-maps/react is fully compatible with react-simple-maps
But in case feel free to open an issue or pull request

Migration checklist

Step	Change
Data	Geographies.geography -> MapBase.data
Data transform	Geographies.parseGeographies -> MapBase.dataTransformer
Style prop	Geography.style -> MapFeature.styles
Style states	style.pressed -> styles.active
Zoom wrapper	ZoomableGroup -> MapZoom
Marker	Marker -> MapMarker
Line	Line -> MapLine
Annotation	Annotation -> MapAnnotation
Graticule	Graticule -> MapGraticule
Sphere	Sphere -> MapGraticule (background/border)

1. Migrate data

• Geographies.geography -> MapBase.data
MapBase.data supports only data objects, not URLs, data fetching is non-opinionated
• Geographies.parseGeographies -> MapBase.dataTransformer

import { MapBase, MapFeatures, type MapData } from '@d3-maps/react'
import { useEffect, useState } from 'react'

export function WorldMap() {
  const [data, setData] = useState<MapData | null>(null)

  useEffect(() => {
    fetch('/world-110m.json')
      .then((res) => res.json())
      .then((json) => setData(json as MapData))
  }, [])

  if (!data) return null

  return (
    <MapBase
      data={data}
      dataTransformer={(features) => features.filter((f) => f.properties?.name !== 'Antarctica')}
    >
      <MapFeatures />
    </MapBase>
  )
}

2. Rename style prop

• Geography.style -> MapFeature.styles
• style.pressed -> styles.active

This style model is supported by MapFeature, MapFeatures, MapMarker, MapMesh, and MapGraticule

<MapFeature
  styles={{
    default: { fill: '#e2e8f0' },
    hover: { fill: '#fb923c' },
    active: { fill: '#ea580c' },
  }}
/>

You can still use plain SVG attributes like fill, stroke, and strokeWidth directly on map components.

3. Rename zoom component

ZoomableGroup -> MapZoom and rename events:

• onMoveStart -> onZoomStart
• onMove -> onZoom
• onMoveEnd -> onZoomEnd

<MapBase data={data}>
  <MapZoom
    zoom={1}
    minZoom={1}
    maxZoom={8}
    onZoomStart={() => {}}
    onZoom={() => {}}
    onZoomEnd={() => {}}
  >
    <MapFeatures />
  </MapZoom>
</MapBase>

4. Rename marker component

Marker -> MapMarker.

<MapMarker coordinates={[-74.006, 40.7128]}>
  <circle r={4} fill="#ff6f26" />
  <text y={-8} textAnchor="middle" fontSize={12}>NYC</text>
</MapMarker>

5. Rename graticule component

Graticule -> MapGraticule.

<MapGraticule />

6. Migrate sphere component

Sphere -> MapGraticule with background and/or border.

<MapGraticule background="#eee" border="#333" />

7. Rename line component

Line -> MapLine

react-simple-maps line props map directly to MapLine.coordinates

<MapLine
  coordinates={[
    [-74.006, 40.7128],
    [-118.2437, 34.0522],
  ]}
/>

8. Migrate annotation component

Annotation -> MapAnnotation

<MapBase data={data}>
  <MapFeatures />
  <MapAnnotation
    coordinates={[2.3522, 48.8566]}
    length={36}
    angle={-35}
    margin={10}
    stroke="#ff6f26"
    strokeWidth={2}
  >
    <text
      y={-6}
      textAnchor="middle"
      fontSize={12}
    >
      Paris
    </text>
  </MapAnnotation>
</MapBase>

Component mapping

react-simple-maps	d3-maps
ComposableMap	MapBase
Geographies	MapFeatures
Geography	MapFeature
Marker	MapMarker
Line	MapLine
ZoomableGroup	MapZoom
Graticule	MapGraticule
Sphere	MapGraticule (background/border) or a custom SVG layer
Annotation	MapAnnotation