{"id":11858,"library":"react-simple-maps","title":"React Simple Maps","description":"React Simple Maps is a component library designed to facilitate the creation of interactive SVG maps within React applications. As of version 3.0.0, released in July 2022, it provides a declarative API built on top of `d3-geo` and `topojson-client`, specifically handling common complexities like panning, zooming, and rendering optimizations. Unlike many mapping solutions, it does not bundle map data; users are required to provide their own GeoJSON or TopoJSON files. This approach makes the library lean and flexible, allowing seamless integration with other React ecosystem tools such as `react-spring` or `react-annotation`. While its average release cycle was historically around 145 days, v3.0.0 has been the latest stable release for some time, suggesting a slower development cadence or maintenance mode. Its core differentiator lies in its minimalist design, offering building blocks for custom map charts without unnecessary bloat, focusing on the core task of rendering and interacting with geographic data.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/zcreativelabs/react-simple-maps","tags":["javascript","react","maps","charts","worldmap","usa","d3-geo"],"install":[{"cmd":"npm install react-simple-maps","lang":"bash","label":"npm"},{"cmd":"yarn add react-simple-maps","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-simple-maps","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for type checking component props, common in older React codebases.","package":"prop-types","optional":false},{"reason":"Core React library, required for all React components.","package":"react","optional":false},{"reason":"Required for rendering React components to the DOM.","package":"react-dom","optional":false}],"imports":[{"note":"Main container component for all map elements. ESM imports are standard for modern React libraries.","wrong":"const ComposableMap = require('react-simple-maps').ComposableMap;","symbol":"ComposableMap","correct":"import { ComposableMap } from 'react-simple-maps';"},{"note":"Used to fetch and process GeoJSON/TopoJSON data. Always imported as a named export.","wrong":"import Geographies from 'react-simple-maps/lib/Geographies';","symbol":"Geographies","correct":"import { Geographies } from 'react-simple-maps';"},{"note":"Renders individual geographic shapes (e.g., countries, states). Utilizes a `key` prop, often `geo.rsmKey`.","wrong":"import { default as Geography } from 'react-simple-maps/Geography';","symbol":"Geography","correct":"import { Geography } from 'react-simple-maps';"},{"note":"Component for placing points of interest on the map. Supports custom SVG content inside.","wrong":"const { Marker } = require('react-simple-maps');","symbol":"Marker","correct":"import { Marker } from 'react-simple-maps';"},{"note":"Enables interactive zooming and panning features. Wrap other map components within it.","wrong":"import * as ZoomableGroup from 'react-simple-maps/ZoomableGroup';","symbol":"ZoomableGroup","correct":"import { ZoomableGroup } from 'react-simple-maps';"}],"quickstart":{"code":"import React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport { ComposableMap, Geographies, Geography, Marker } from 'react-simple-maps';\n\nconst geoUrl = 'https://raw.githubusercontent.com/deldersveld/topojson/master/world-countries.json';\n\nconst markers = [\n  { markerOffset: -15, name: 'Buenos Aires', coordinates: [-58.3816, -34.6037] },\n  { markerOffset: -15, name: 'La Paz', coordinates: [-68.1193, -16.4897] },\n  { markerOffset: 25, name: 'Brasília', coordinates: [-47.8825, -15.7942] },\n  { markerOffset: 25, name: 'Santiago', coordinates: [-70.6693, -33.4489] },\n  { markerOffset: -15, name: 'Bogotá', coordinates: [-74.0721, 4.7110] },\n  { markerOffset: 25, name: 'Quito', coordinates: [-78.4678, -0.1807] }\n];\n\nconst MapChart = () => {\n  return (\n    <ComposableMap\n      projection=\"geoEqualEarth\"\n      projectionConfig={{\n        scale: 160\n      }}\n      style={{\n        width: '100%',\n        height: 'auto'\n      }}\n    >\n      <Geographies geography={geoUrl}>\n        {({ geographies }) =>\n          geographies.map((geo) => (\n            <Geography\n              key={geo.rsmKey}\n              geography={geo}\n              fill=\"#D6D6DA\"\n              stroke=\"#FFFFFF\"\n              strokeWidth={0.5}\n            />\n          ))\n        }\n      </Geographies>\n      {markers.map(({ name, coordinates, markerOffset }) => (\n        <Marker key={name} coordinates={coordinates}>\n          <circle r={8} fill=\"#F00\" stroke=\"#fff\" strokeWidth={2} />\n          <text\n            textAnchor=\"middle\"\n            y={markerOffset}\n            style={{ fontFamily: 'system-ui', fill: '#5D5A6D', fontSize: '10px' }}\n          >\n            {name}\n          </text>\n        </Marker>\n      ))}\n    </ComposableMap>\n  );\n};\n\nconst root = ReactDOM.createRoot(document.getElementById('root'));\nroot.render(<MapChart />);","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0 (with React >=19)"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Performance can significantly degrade when using very large or highly detailed TopoJSON/GeoJSON files, especially when combined with many markers or complex styling.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure you have a valid `geoUrl` pointing to a GeoJSON or TopoJSON file. Popular sources include Natural Earth or `deldersveld/topojson` on GitHub.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"<3.0.0 (depending on `d3-color` version)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"SyntaxError: Cannot use import statement outside a module"},{"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.","cause":"Incorrect `projectionConfig` properties, especially `scale` and `center`, or issues with the loaded GeoJSON/TopoJSON data.","error":"The map is very small or not appearing at all."},{"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} />`.","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.","error":"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."},{"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.","cause":"The `geoUrl` for the TopoJSON/GeoJSON file is incorrect, inaccessible, or there's a network issue (e.g., CORS).","error":"Uncaught (in promise) TypeError: Failed to fetch"}],"ecosystem":"npm"}