Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ComposableMap
✓ import { ComposableMap } from 'react-simple-maps';
✗ const ComposableMap = require('react-simple-maps').ComposableMap;
Main container component for all map elements. ESM imports are standard for modern React libraries.
Geographies
✓ import { Geographies } from 'react-simple-maps';
✗ import Geographies from 'react-simple-maps/lib/Geographies';
Used to fetch and process GeoJSON/TopoJSON data. Always imported as a named export.
Geography
✓ import { Geography } from 'react-simple-maps';
✗ import { default as Geography } from 'react-simple-maps/Geography';
Renders individual geographic shapes (e.g., countries, states). Utilizes a `key` prop, often `geo.rsmKey`.
Marker
✓ import { Marker } from 'react-simple-maps';
✗ const { Marker } = require('react-simple-maps');
Component for placing points of interest on the map. Supports custom SVG content inside.
ZoomableGroup
✓ import { ZoomableGroup } from 'react-simple-maps';
✗ import * as ZoomableGroup from 'react-simple-maps/ZoomableGroup';
Enables interactive zooming and panning features. Wrap other map components within it.
This quickstart renders a basic world map using the `geoEqualEarth` projection, fetching a TopoJSON file from a URL. It then overlays a set of predefined markers with labels for several South American capitals. The map is set to fill 100% width and auto height.
import React from 'react';
import ReactDOM from 'react-dom/client';
import { ComposableMap, Geographies, Geography, Marker } from 'react-simple-maps';
const geoUrl = 'https://raw.githubusercontent.com/deldersveld/topojson/master/world-countries.json';
const markers = [
{ markerOffset: -15, name: 'Buenos Aires', coordinates: [-58.3816, -34.6037] },
{ markerOffset: -15, name: 'La Paz', coordinates: [-68.1193, -16.4897] },
{ markerOffset: 25, name: 'Brasília', coordinates: [-47.8825, -15.7942] },
{ markerOffset: 25, name: 'Santiago', coordinates: [-70.6693, -33.4489] },
{ markerOffset: -15, name: 'Bogotá', coordinates: [-74.0721, 4.7110] },
{ markerOffset: 25, name: 'Quito', coordinates: [-78.4678, -0.1807] }
];
const MapChart = () => {
return (
<ComposableMap
projection="geoEqualEarth"
projectionConfig={{
scale: 160
}}
style={{
width: '100%',
height: 'auto'
}}
>
<Geographies geography={geoUrl}>
{({ geographies }) =>
geographies.map((geo) => (
<Geography
key={geo.rsmKey}
geography={geo}
fill="#D6D6DA"
stroke="#FFFFFF"
strokeWidth={0.5}
/>
))
}
</Geographies>
{markers.map(({ name, coordinates, markerOffset }) => (
<Marker key={name} coordinates={coordinates}>
<circle r={8} fill="#F00" stroke="#fff" strokeWidth={2} />
<text
textAnchor="middle"
y={markerOffset}
style={{ fontFamily: 'system-ui', fill: '#5D5A6D', fontSize: '10px' }}
>
{name}
</text>
</Marker>
))}
</ComposableMap>
);
};
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<MapChart />);
Debug
Known issues
breakingThe official `react-simple-maps` package, as of its current version 3.0.0, is not fully compatible with React 19 due to unaddressed dependency issues. Users targeting React 19 should be aware that they might need to use a community-maintained fork or pin older React versions.fixFor React 19 compatibility, consider using a community-maintained fork like `@vnedyalk0v/react19-simple-maps` or downgrade your React version. Otherwise, monitor the official repository for updates.
affects: >=3.0.0 (with React >=19)
gotchaMap components might appear extremely small or not at all if the `projectionConfig.scale` property within `ComposableMap` is too low, or if the `center` property positions the map off-screen.fixAdjust the `scale` value in `projectionConfig` to a higher number to zoom in, and use the `center` property to position the map correctly. Using `ZoomableGroup` can also help interactively locate the map during development.
affects: >=1.0.0
gotchaPerformance can significantly degrade when using very large or highly detailed TopoJSON/GeoJSON files, especially when combined with many markers or complex styling.fixUse simplified map files (e.g., `world-50m.json` instead of `world-110m.json` for general overview). Consider applying `pointerEvents: 'none'` to `Geographies` if hover interactions are not needed to improve rendering performance. Optimize marker rendering and avoid heavy `stroke` styles on many paths.
affects: >=1.0.0
gotchaThe library does not include any map data. Users must provide valid GeoJSON or TopoJSON files themselves, typically by fetching them from an external URL or including them locally.fixEnsure you have a valid `geoUrl` pointing to a GeoJSON or TopoJSON file. Popular sources include Natural Earth or `deldersveld/topojson` on GitHub.
affects: >=1.0.0
gotchaOlder versions of `d3-color` (a transitive dependency) had known security vulnerabilities (CWE-400). While `react-simple-maps` itself is a wrapper, ensuring up-to-date dependencies is crucial.fixRegularly run `npm audit` or `yarn audit` and update your dependencies to their latest secure versions. If an audit report flags `d3-color`, explicitly install a version of `d3-color` that addresses the vulnerability (e.g., `npm install d3-color@^3.1.0`).
affects: <3.0.0 (depending on `d3-color` version)
Errors
Common errors & fixes
SyntaxError: Cannot use import statement outside a module
Attempting to use ES module `import` syntax in a CommonJS (CJS) environment, or a build process that doesn't correctly transpile ESM to CJS. The library primarily uses ESM.
fixEnsure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json` for Node.js, or using a bundler like Webpack/Rollup/Vite that handles ESM correctly). For older environments, a transpilation step is necessary.
The map is very small or not appearing at all.
Incorrect `projectionConfig` properties, especially `scale` and `center`, or issues with the loaded GeoJSON/TopoJSON data.
fixAdjust `projectionConfig={{ scale: N, center: [lat, lon] }}` on `ComposableMap`. Start with a low scale to locate the map, then increase. Verify your `geoUrl` is correct and the map file is valid. Error: Objects are not valid as a React child (found: object with keys {type, properties, geometry, rsmKey}). If you meant to render a collection of children, use an array instead.
Attempting to render the raw `geo` object directly within JSX instead of wrapping it in the `Geography` component or providing a valid React element.
fixEnsure that within the `Geographies` component's render prop, each `geo` object is passed to a `Geography` component, like so: `<Geography key={geo.rsmKey} geography={geo} />`. Uncaught (in promise) TypeError: Failed to fetch
The `geoUrl` for the TopoJSON/GeoJSON file is incorrect, inaccessible, or there's a network issue (e.g., CORS).
fixDouble-check the `geoUrl` for typos. Verify the URL is publicly accessible. If fetching from a different domain, ensure the server provides appropriate CORS headers. For local development, ensure the file path is correct relative to your public assets.
Audit
Dependencies
prop-typesrequiredUsed for type checking component props, common in older React codebases.
reactrequiredCore React library, required for all React components.
react-domrequiredRequired for rendering React components to the DOM.