Migrate from react-simple-maps

@d3-maps/react is fully compatible with react-simple-maps, supports React 19 an has more features under the hood.

Feel free to open an issue or a pull request if something is missing.

Migration checklist

Step	Change
Data	Geographies.geography -> MapFeatures.data
Data transform	Geographies.parseGeographies -> MapFeatures.transformer
Fit	ComposableMap sizing + geography bounds -> MapBase.fit
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 -> MapSphere

1. Migrate data

• Geographies.geography -> MapFeatures.data
• Geographies.parseGeographies -> MapFeatures.transformer

import { MapBase, MapFeatures } from '@d3-maps/react'
import { use, useCallback } from 'react'

const worldPromise = import('@d3-maps/atlas/world/countries')
  .then((m) => m.default)

export function WorldMap() {
  const world = use(worldPromise)
  const filterAntarctica = useCallback((features) => {
    return features.filter((f) => f.properties?.name !== 'Antarctica')
  }, [])

  return (
    <MapBase>
      <MapFeatures
        data={data}
        transformer={filterAntarctica}
      />
    </MapBase>
  )
}

2. Rename style prop

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

<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>
  <MapZoom
    minZoom={1}
    maxZoom={8}
    onZoomStart={() => {}}
    onZoom={() => {}}
    onZoomEnd={() => {}}
  >
    <MapFeatures data={data} />
  </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 -> MapSphere

<MapSphere fill="#eee" stroke="#999">
  <MapFeatures data={mapData} />
</MapSphere>

7. Rename line component

Line -> MapLine

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

8. Migrate annotation component

Annotation -> MapAnnotation

<MapBase>
  <MapFeatures data={data} />
  <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	MapSphere or a custom SVG layer
Annotation	MapAnnotation