react-native-simple-map

Create beautiful, interactive SVG maps in React Native with d3-geo and TopoJSON using a declarative API. A React Native port of react-simple-maps.

Features

• 🗺️ 15+ map projections — Mercator, Orthographic, Equal Earth, Natural Earth, and more
• 📍 Markers — Place markers at any coordinates with custom SVG children
• ✏️ Annotations — Label locations with connector lines
• 🛫 Lines — Draw routes/connections between coordinates
• 🌐 Graticule — Latitude/longitude grid overlay
• 🔵 Sphere — Globe boundary with clipping
• 👆 Interactive — Press handlers on geographies and markers
• 🔍 Zoom & Pan — Pinch-to-zoom and drag gestures (optional, separate import)
• 📦 TypeScript — Full type definitions included
• ⚡ Tree-shakeable — ESM output, zoom module is a separate entry point

Installation

npm install react-native-simple-map react-native-svg

Peer Dependencies

Package	Required	Purpose
react-native-svg	Yes	SVG rendering
react-native-gesture-handler	Only for ZoomableGroup	Gesture handling
react-native-reanimated	Only for ZoomableGroup	Smooth animations

If you want zoom/pan support:

npm install react-native-gesture-handler react-native-reanimated

Note: After installing native dependencies, rebuild your app (npx react-native run-android or run-ios).

Quick Start

import { ComposableMap, Geographies, Geography } from 'react-native-simple-map';

const geoUrl = 'https://cdn.jsdelivr.net/npm/world-atlas@2/countries-110m.json';

export default function WorldMap() {
  return (
    <ComposableMap>
      <Geographies geography={geoUrl}>
        {({ geographies }) =>
          geographies.map((geo) => (
            <Geography
              key={geo.rsmKey}
              geography={geo}
              fill="#D6D6DA"
              stroke="#FFFFFF"
              strokeWidth={0.5}
            />
          ))
        }
      </Geographies>
    </ComposableMap>
  );
}

Components

<ComposableMap>

Root container that sets up the SVG canvas and map projection.

<ComposableMap
  width={800}           // SVG viewport width (default: 800)
  height={600}          // SVG viewport height (default: 600)
  projection="geoMercator"  // Projection name or factory function
  projectionConfig={{
    scale: 140,
    center: [0, 0],
    rotate: [0, 0, 0],
  }}
>
  {children}
</ComposableMap>

Available projections: geoEqualEarth, geoMercator, geoOrthographic, geoNaturalEarth1, geoAlbers, geoAlbersUsa, geoAzimuthalEqualArea, geoAzimuthalEquidistant, geoConicConformal, geoConicEqualArea, geoConicEquidistant, geoEquirectangular, geoGnomonic, geoStereographic, geoTransverseMercator

---

<Geographies>

Loads and parses TopoJSON data, providing geography features to children.

<Geographies geography={geoUrl}>
  {({ geographies, outline, borders, path, projection }) =>
    geographies.map((geo) => (
      <Geography key={geo.rsmKey} geography={geo} />
    ))
  }
</Geographies>

Prop	Type	Description
geography	string | object	TopoJSON URL or inline object
children	function	Render function receiving { geographies, outline, borders, path, projection }
parseGeographies	function	Optional transform applied to features array

---

<Geography>

Renders a single geographic feature as an SVG path.

<Geography
  geography={geo}
  fill="#EAEAEC"
  stroke="#D6D6DA"
  strokeWidth={0.5}
  onPress={(geo) => console.log(geo.properties.name)}
  style={{
    default: { fill: '#D6D6DA' },
    pressed: { fill: '#E42' },
  }}
/>

Prop	Type	Description
geography	GeographyFeature	Feature object from Geographies render prop
fill	string	Fill color
stroke	string	Border color
strokeWidth	number	Border width
onPress	(geo) => void	Press handler
onPressIn	(geo) => void	Touch start handler
onPressOut	(geo) => void	Touch end handler
style	{ default?, pressed? }	Style states

---

<Marker>

Places children at projected geographic coordinates.

import { Circle } from 'react-native-svg';

<Marker coordinates={[-74.006, 40.7128]}>
  <Circle r={4} fill="#F53" />
</Marker>

Prop	Type	Description
coordinates	[number, number]	[longitude, latitude]
children	ReactNode	SVG elements to render at the location
onPress	() => void	Press handler

---

<Line>

Draws a geodesic line between two or more coordinates.

<Line
  from={[-74.006, 40.7128]}
  to={[2.3522, 48.8566]}
  stroke="#F53"
  strokeWidth={2}
/>

Prop	Type	Default	Description
from	[number, number]	[0, 0]	Start coordinates
to	[number, number]	[0, 0]	End coordinates
coordinates	[number, number][]	—	Multi-point path (overrides from/to)
stroke	string	"currentColor"	Line color
strokeWidth	number	3	Line width
fill	string	"transparent"	Fill (usually transparent for lines)

---

<Annotation>

Renders a label with a connector line from a geographic coordinate.

import { Text as SvgText } from 'react-native-svg';

<Annotation subject={[2.3522, 48.8566]} dx={-40} dy={-30}>
  <SvgText fontSize={12} fill="#333">Paris</SvgText>
</Annotation>

Prop	Type	Default	Description
subject	[number, number]	—	Target coordinates
dx	number	30	Horizontal offset for label
dy	number	30	Vertical offset for label
curve	number	0	Connector line curvature
connectorProps	object	{}	SVG props for the connector path

---

<Graticule>

Renders a latitude/longitude grid.

<Graticule stroke="#ccc" strokeWidth={0.3} step={[20, 20]} />

Prop	Type	Default	Description
fill	string	"transparent"	Grid fill
stroke	string	"#ccc"	Grid line color
strokeWidth	number	0.5	Grid line width
step	[number, number]	[10, 10]	Grid spacing in degrees

---

<Sphere>

Renders the globe boundary with an optional clip path.

<Sphere fill="#E8F4FD" stroke="#999" strokeWidth={0.5} />

Prop	Type	Default	Description
id	string	"rsm-sphere"	ClipPath ID
fill	string	"transparent"	Background fill
stroke	string	"#000"	Border color
strokeWidth	number	0.5	Border width

---

<ZoomableGroup> (separate import)

Adds pinch-to-zoom and drag-to-pan gestures. Requires react-native-gesture-handler and react-native-reanimated.

import { ZoomableGroup } from 'react-native-simple-map/zoom';
import { GestureHandlerRootView } from 'react-native-gesture-handler';

<GestureHandlerRootView style={{ flex: 1 }}>
  <ComposableMap>
    <ZoomableGroup
      center={[0, 0]}
      zoom={1}
      minZoom={1}
      maxZoom={8}
      onMove={({ x, y, zoom }) => console.log(zoom)}
    >
      <Geographies geography={geoUrl}>
        {({ geographies }) =>
          geographies.map((geo) => (
            <Geography key={geo.rsmKey} geography={geo} />
          ))
        }
      </Geographies>
    </ZoomableGroup>
  </ComposableMap>
</GestureHandlerRootView>

Prop	Type	Default	Description
center	[number, number]	[0, 0]	Initial center coordinates
zoom	number	1	Initial zoom level
minZoom	number	1	Minimum zoom
maxZoom	number	8	Maximum zoom
translateExtent	[[x0, y0], [x1, y1]]	—	Pan bounds
onMoveStart	function	—	Gesture start callback
onMove	function	—	Gesture move callback { x, y, zoom }
onMoveEnd	function	—	Gesture end callback

Important: Wrap your app (or screen) in <GestureHandlerRootView> when using ZoomableGroup.

---

Hooks

useMapContext()

Access the map projection and path generator from any child component.

import { useMapContext } from 'react-native-simple-map';

const { projection, path, width, height } = useMapContext();

useGeographies()

Fetch and parse TopoJSON data programmatically.

import { useGeographies } from 'react-native-simple-map';

const { geographies, outline, borders } = useGeographies({ geography: geoUrl });

---

Geography Data

This library works with TopoJSON format. Recommended sources:

• World Atlas — https://cdn.jsdelivr.net/npm/world-atlas@2/countries-110m.json
• US Atlas — https://cdn.jsdelivr.net/npm/us-atlas@3/states-10m.json
• Custom — Any valid TopoJSON file or URL

---

Comparison with react-simple-maps (Web)

This library aims for API parity with react-simple-maps. Key differences for React Native:

Web	React Native
className prop	Use inline SVG props (fill, stroke, etc.)
onMouseEnter/onMouseLeave	onPress/onPressIn/onPressOut
style.hover state	Not available (no hover on mobile)
d3-zoom (mouse wheel)	Pinch + pan gestures via react-native-gesture-handler
Single import	ZoomableGroup is a separate import (/zoom)

---

TypeScript

All components are fully typed. Import types directly:

import type {
  ComposableMapProps,
  GeographiesProps,
  GeographyProps,
  GeographyFeature,
  MarkerProps,
  AnnotationProps,
  LineProps,
  SphereProps,
  GraticuleProps,
  ZoomableGroupProps,
  ProjectionConfig,
  MapContextValue,
  ZoomPanContextValue,
} from 'react-native-simple-map';

---

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT