React Simple Maps

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause 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.
  fix Ensure 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.

  cause Incorrect `projectionConfig` properties, especially `scale` and `center`, or issues with the loaded GeoJSON/TopoJSON data.
  fix Adjust `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.

  cause Attempting to render the raw `geo` object directly within JSX instead of wrapping it in the `Geography` component or providing a valid React element.
  fix Ensure 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

  cause The `geoUrl` for the TopoJSON/GeoJSON file is incorrect, inaccessible, or there's a network issue (e.g., CORS).
  fix Double-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.

Warnings

• breaking The 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.
  Fix: For 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.
• gotcha Map 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.
  Fix: Adjust 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.
• gotcha Performance can significantly degrade when using very large or highly detailed TopoJSON/GeoJSON files, especially when combined with many markers or complex styling.
  Fix: Use 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.
• gotcha The 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.
  Fix: Ensure you have a valid `geoUrl` pointing to a GeoJSON or TopoJSON file. Popular sources include Natural Earth or `deldersveld/topojson` on GitHub.
• gotcha Older 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.
  Fix: Regularly 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`).

Install

• npm install react-simple-maps npm
• yarn add react-simple-maps yarn
• pnpm add react-simple-maps pnpm

Imports

• ComposableMap
  wrong:

  const ComposableMap = require('react-simple-maps').ComposableMap;

  correct:

  import { ComposableMap } from 'react-simple-maps';

  Main container component for all map elements. ESM imports are standard for modern React libraries.
• Geographies
  wrong:

  import Geographies from 'react-simple-maps/lib/Geographies';

  correct:

  import { Geographies } from 'react-simple-maps';

  Used to fetch and process GeoJSON/TopoJSON data. Always imported as a named export.
• Geography
  wrong:

  import { default as Geography } from 'react-simple-maps/Geography';

  correct:

  import { Geography } from 'react-simple-maps';

  Renders individual geographic shapes (e.g., countries, states). Utilizes a `key` prop, often `geo.rsmKey`.
• Marker
  wrong:

  const { Marker } = require('react-simple-maps');

  correct:

  import { Marker } from 'react-simple-maps';

  Component for placing points of interest on the map. Supports custom SVG content inside.
• ZoomableGroup
  wrong:

  import * as ZoomableGroup from 'react-simple-maps/ZoomableGroup';

  correct:

  import { ZoomableGroup } from 'react-simple-maps';

  Enables interactive zooming and panning features. Wrap other map components within it.

Quickstart

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 />);