@vnedyalk0v/react19-simple-maps

Create interactive SVG maps in React with d3-geo and topojson using a TypeScript-first API for React 19+.

Modernized fork of react-simple-maps with React 19 support and TypeScript-first tooling.

Why this package?

• Built specifically for React 19+ instead of preserving compatibility with older React release lines.
• Ships as a modern ESM-only library with explicit exports, tree-shakeable output, and TypeScript definitions.
• Provides a TypeScript-first API with branded coordinate helpers that reduce common map-coordinate mistakes.
• Includes safer URL-based geography loading with validation, HTTPS-first defaults, response-size checks, and optional SRI helpers.

Key Features

• React 19+ only (peer dependencies)
• ESM-only build with tree-shaking and type definitions
• TypeScript-first API with branded coordinate helpers
• Core components: ComposableMap, Geographies, Geography, ZoomableGroup, Marker, Annotation, Line, Sphere, Graticule
• Optional error boundary with a custom fallback for geography loading
• Geography fetching utilities with validation (HTTPS-only default, private IP blocking, content-type/size checks) and optional SRI helpers
• Opt-in debug logging via debug prop or REACT_SIMPLE_MAPS_DEBUG

Quick Links

• npm Package
• Examples
• Support Policy
• CI/CD Architecture
• Changelog
• Issues
• Discussions

Installation

From npm Registry (Recommended)

# npm
npm install @vnedyalk0v/react19-simple-maps

# yarn
yarn add @vnedyalk0v/react19-simple-maps

# pnpm
pnpm add @vnedyalk0v/react19-simple-maps

ESM-only: This package only supports import syntax. require(...) is not supported.

Requirements

• React: 19.0.0 or higher (peer dependency)
• React DOM: 19.0.0 or higher (peer dependency)
• Node.js: 24.15.0 or higher on the Node 24 line for development and builds — the line CI validates. Node 25 is excluded by the locked test toolchain; see the Support Policy.
• TypeScript: 5.0.0 or higher (recommended)

For support expectations, compatibility boundaries, and release behavior, see the Support Policy.

Utilities Subpath

You can import helper utilities directly from the ./utils subpath:

import {
  validateGeographyUrl,
  configureSRI,
} from '@vnedyalk0v/react19-simple-maps/utils';

The ./utils entry includes both recommended helpers and more advanced low-level utilities. Prefer the documented helpers below unless you have a specific integration need.

Recommended ./utils helpers

For most applications, start with these helpers:

• Geography loading and preparation: fetchGeographiesCache, preloadGeography, getFeatures, getMesh, prepareFeatures, prepareMesh, createConnectorPath
• Validation and security: validateGeographyUrl, validateGeographyData, configureGeographySecurity, enableDevelopmentMode
• Integrity helpers: configureSRI, enableStrictSRI, disableSRI, addCustomSRI, getSRIForUrl, validateSRI
• Data guards: isTopology, isFeatureCollection, isFeature, isValidGeographyUrl, isValidGeographyData

Migration Notes (from react-simple-maps)

1. Replace package + import path: react-simple-maps → @vnedyalk0v/react19-simple-maps.
2. For TypeScript, use branded helpers like createCoordinates() (or an explicit cast) for Coordinates.
3. Geography event handlers receive (event, data) where data includes geography info (centroid, bounds, etc.).

Quick Start

import React from 'react';
import {
  ComposableMap,
  Geographies,
  Geography,
  createCoordinates,
} from '@vnedyalk0v/react19-simple-maps';

const geoUrl = 'https://unpkg.com/[email protected]/countries-110m.json';

const MapChart = () => {
  return (
    <ComposableMap
      projection="geoEqualEarth"
      projectionConfig={{
        scale: 147,
        center: createCoordinates(0, 0),
      }}
      width={800}
      height={500}
    >
      <Geographies geography={geoUrl}>
        {({ geographies }) =>
          geographies.map((geo) => (
            <Geography
              key={geo.rsmKey}
              geography={geo}
              style={{
                default: { fill: '#D6D6DA', outline: 'none' },
                hover: { fill: '#F53', outline: 'none' },
                pressed: { fill: '#E42', outline: 'none' },
              }}
            />
          ))
        }
      </Geographies>
    </ComposableMap>
  );
};

export default MapChart;

Core Components

ComposableMap

The main wrapper component that provides SVG context and projection setup.

Common props:

• projection - Map projection (string name or d3-geo projection function)
• projectionConfig - Configuration for built-in projections
• width, height - SVG dimensions
• className - CSS class name
• debug - Enable opt-in debug logging (default: false)

Geographies

Renders geographic features from TopoJSON or GeoJSON data.

Notable props:

• geography - URL string, TopoJSON object, or GeoJSON FeatureCollection
• parseGeographies - Optional function to transform geography data
• errorBoundary - Enable the built-in error boundary
• onGeographyError, fallback - Error handling hooks when errorBoundary is enabled. A caught error clears when the geography URL changes; for inline data, change the key on Geographies to reset it.

Geography

Individual geographic feature component with enhanced event handlers.

All event handlers receive (event, GeographyEventData) where GeographyEventData includes: geography, centroid, bounds, and coordinates.

ZoomableGroup

Zoom and pan with both simple and advanced APIs.

import {
  ZoomableGroup,
  createCoordinates,
  createZoomConfig,
} from '@vnedyalk0v/react19-simple-maps';

<ZoomableGroup
  zoom={1}
  center={createCoordinates(0, 0)}
  {...createZoomConfig(0.5, 8)}
>
  {/* Content */}
</ZoomableGroup>;

Set enableZoom={false} to keep the current scale while allowing pan gestures, or enablePan={false} to reject pan gestures and zoom around the viewport center. Setting both to false disables user gestures. Explicit center and zoom updates still reposition the map. These controls also apply when a custom filterZoomEvent is provided.

Marker & Annotation

Use Marker for custom points and Annotation for callouts.

Additional Components

• Line - Draw lines between coordinates; pass coordinates, or both from and to
• Graticule - Add coordinate grid lines
• Sphere - Add map outline/background
• GeographyErrorBoundary - Explicit error boundary wrapper; pass resetKey to clear a caught error when that value changes
• MapWithMetadata - Wrapper that renders metadata and a ComposableMap

MapWithMetadata renders page metadata and JSON-LD for a ComposableMap. Choose a preset (worldMap by default) for the structured data. The countryMap, cityMap, and dataVisualization presets take their subject through presetArgs; without it they add no content.

<MapWithMetadata
  metadata={{
    title: 'France',
    description: 'Regions of France',
    keywords: ['france', 'map'],
    author: '',
    canonicalUrl: '',
  }}
  preset="countryMap"
  presetArgs={['France']}
>
  {/* Map content */}
</MapWithMetadata>

TypeScript Support

Branded types help prevent coordinate mistakes:

import {
  createCoordinates,
  createLongitude,
  createLatitude,
} from '@vnedyalk0v/react19-simple-maps';

const lon = createLongitude(-74.006);
const lat = createLatitude(40.7128);
const coords = createCoordinates(-74.006, 40.7128);

Use createRotationAngles(lambda, phi, gamma) and createParallels(a, b) for projectionConfig:

import {
  ComposableMap,
  createRotationAngles,
} from '@vnedyalk0v/react19-simple-maps';

<ComposableMap
  projection="geoOrthographic"
  projectionConfig={{ rotate: createRotationAngles(-10, -20, 0) }}
/>;

Geography Utilities

Extract geographic data for interactions and labels:

import {
  getGeographyCentroid,
  getGeographyBounds,
  getBestGeographyCoordinates,
} from '@vnedyalk0v/react19-simple-maps';

Map Data Sources

• Natural Earth
• TopoJSON Collection
• World Atlas
• US Atlas

Security Utilities

The ./utils subpath includes helpers for safer geography fetching. When you use URL-based geography data in Geographies, the internal fetch path applies URL validation, HTTPS-only defaults, resolved-hostname checks in server environments, response size checks, and optional SRI validation.

Prefer fetchGeographiesCache for direct utility-based loading. fetchGeographies remains available for compatibility but is deprecated.

Fetched GeoJSON preserves features whose geometry is null. Both fetch helpers declare this nullable output; check feature.geometry !== null before accessing its fields. getFeatures(data) omits those unlocated features and passes non-null geometries to parseGeographies. Inline GeoJSON component props and public data guards continue to require non-null geometries. See the raw-data example for both forms.

Configuration set through configureGeographySecurity, configureSRI, or enableStrictSRI from ./utils also applies to map components imported from the main package. Geography request timeouts cover redirects and reading the response body.

generateSRIHash validates redirect targets against the same URL and resolved-hostname policy as geography loading, omits credentials, and enforces the configured timeout and response size limit. Browsers cannot inspect manual cross-origin redirects; use the final resource URL directly when a source redirects.

import {
  configureGeographySecurity,
  enableDevelopmentMode,
} from '@vnedyalk0v/react19-simple-maps/utils';

configureGeographySecurity({
  TIMEOUT_MS: 5000,
  MAX_RESPONSE_SIZE: 10 * 1024 * 1024,
});

if (process.env.NODE_ENV === 'development') {
  enableDevelopmentMode(true); // allow HTTP localhost
}

In production, the fetch path keeps HTTPS-only protections enabled and does not disable integrity checks for known geography sources.

Debugging

Enable debug logging globally via environment variable or per map:

REACT_SIMPLE_MAPS_DEBUG=true

<ComposableMap debug={true}>{/* Map content */}</ComposableMap>

Development

npm install
npm run dev

npm run ci is the full validation gate and runs build, type-check, lint, format check, tests, and build verification:

npm run ci

Individual steps are also available: npm run build, npm run test, npm run type-check, npm run lint.

Publishing

Changesets is configured for versioning, release pull requests, and npm publishing. The GitHub Actions workflow in .github/workflows/publish.yml opens or updates a release PR when unreleased changesets exist, validates the required checks for that release PR, and publishes to npm when a validated release is merged to main with the required token configured.

License

MIT licensed. Original work Copyright (c) Richard Zimerman 2017. Fork maintenance Copyright (c) Georgi Nedyalkov 2025. See LICENSE for details.