Registry / maps / react-spatial

react-spatial

library3.0.1jsnpmunverified

React components for building map applications using OpenLayers and MapLibre GL JS. Current version 3.0.1 with peer dependencies on maplibre-gl ^5, mobility-toolbox-js ^3.6, ol ^10, react ^19, and react-dom ^19. Actively maintained by geops. Provides real-time geographic visualization widgets (layers, controls, popups) with tight integration to both OpenLayers and MapLibre. Supports ES6 modules and SASS theming. Differentiates by offering a unified React component set over two major map libraries, built on top of mobility-toolbox-js.

maps

npm install react-spatial

package ↗

INSTALL

IMPORT

SIG · REACT-SPATIAL

react-spatial

mapsjavascriptv3.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

OLMap

✓ import { OLMap } from 'react-spatial'

✗ import OLMap from 'react-spatial'

Named export, not default. ESM only.

MapLibreMap

✓ import { MapLibreMap } from 'react-spatial'

✗ import { MapLibreMap } from '@geops/react-spatial'

Package name is 'react-spatial', not scoped.

LayerService

✓ import { LayerService } from 'react-spatial'

✗ const { LayerService } = require('react-spatial')

CJS require may not work; library is ESM-only.

Layer

✓ import { Layer } from 'react-spatial'

Base Layer class.

Popup

✓ import { Popup } from 'react-spatial'

Popup component.

useLayerService

✓ import { useLayerService } from 'react-spatial'

✗ import useLayerService from 'react-spatial'

Hook is a named export.

Minimal React app displaying an OpenLayers map using OLMap component and LayerService.

import React from 'react'; import { OLMap } from 'react-spatial'; import 'react-spatial/themes/default/index.scss'; function App() { const layerService = new LayerService(); const center = [8.5417, 47.3769]; const zoom = 10; return ( <OLMap layerService={layerService} center={center} zoom={zoom} /> ); } export default App;

Debug

Known issues

breakingVersion 3.0 drops support for OpenLayers <10 and React <18.

fix

Upgrade to ol@^10 and react@^18 or ^19.

affects: >=3.0.0

deprecatedImporting from 'react-spatial/lib/...' is deprecated in v3.

fix

Import from the package root: import { Component } from 'react-spatial'

affects: >=3.0.0

gotchaLayerService must be instantiated and passed to map component; components won't work without it.

fix

Create a new LayerService instance and pass via layerService prop.

affects: *

gotchaSASS file import required for default styling; missing import results in unstyled components.

fix

Add import 'react-spatial/themes/default/index.scss' in your entry file.

affects: *

breakingmobility-toolbox-js peer dependency upgraded to ^3.6 in v3.

fix

Install mobilitiy-toolbox-js@^3.6.

affects: >=3.0.0

gotchaMapLibre components require maplibre-gl peer dep; using older maplibre-gl may cause issues.

fix

Install maplibre-gl@^5.

affects: *

Errors

Common errors & fixes

Module not found: Can't resolve 'react-spatial/themes/default/index.scss'

Missing SASS loader in webpack/Vite configuration or missing theme import.

fix

Ensure your bundler supports SCSS (e.g., sass-loader) and correct import path.

Uncaught TypeError: Cannot read properties of undefined (reading 'getLayerService')

LayerService not passed or not properly initialized.

fix

Instantiate LayerService and pass as prop: <OLMap layerService={new LayerService()} />

Cannot find module 'mobility-toolbox-js' or its corresponding type declarations.

Missing peer dependency mobility-toolbox-js.

fix

Run npm install mobility-toolbox-js@^3.6

Attempted import error: 'MapLibreMap' is not exported from 'react-spatial'.

Trying to import a component that doesn't exist in that version (v2).

fix

Upgrade to v3 or check correct component name.

TypeError: Cannot read properties of undefined (reading 'getLayers')

LayerService not yet ready or map not initialized.

fix

Ensure LayerService is initialized before map mount, e.g., in component state.

Upgrade

Version history

3.0.1latest on npm

Audit

Dependencies

maplibre-glrequiredRequired by MapLibre-based components (e.g., MapLibreMap)

mobility-toolbox-jsrequiredCore library dependency for layer management and events

olrequiredRequired by OpenLayers-based components (e.g., OLMap)

reactrequiredPeer dependency for React integration

react-domrequiredPeer dependency for React DOM rendering

Agent activity

24 hits · last 30 days

node

Resources

packagereact-spatial ↗