ol-react-kit

Typed React components and hooks for building interactive OpenLayers maps.

ol-react-kit keeps OpenLayers objects stable while React props change. It provides declarative vector layers, clustering, overlays, interactions, styling utilities, and direct access to the underlying OpenLayers API when needed.

Documentation · Interactive playground · OpenLayers API

Features

• Declarative point, line, polygon, mixed-geometry, cluster, and WebGL layers
• Typed feature events, tooltips, HTML markers, and overlays
• Draw, modify, select, snap, and translate interactions
• Efficient ID-based feature reconciliation for frequently updated datasets
• Built-in style descriptors, style caching, and SVG helpers
• View actions for zooming and fitting coordinates or features
• lon-lat and lat-lon coordinate order support
• Hooks and refs for direct access to OpenLayers maps, views, layers, sources, and interactions

Installation

npm install ol-react-kit ol react react-dom

The package supports React 18 and 19 and uses OpenLayers 10.9.

Import the OpenLayers stylesheet once in your application entry point:

import 'ol/ol.css';

Quick start

import 'ol/ol.css';
import { MapContainer, PointLayer } from 'ol-react-kit';

const places = [
  { id: 'moscow', name: 'Moscow', position: [37.6176, 55.7558] },
  { id: 'kazan', name: 'Kazan', position: [49.1064, 55.7961] },
];

export function PlacesMap() {
  return (
    <MapContainer
      initialCenter={[43.5, 55.8]}
      initialZoom={5}
      controls
      style={{ width: '100%', height: 480 }}
    >
      <PointLayer
        id="places"
        items={places}
        style={{
          circle: {
            radius: 7,
            fill: '#2563eb',
            stroke: { color: '#ffffff', width: 2 },
          },
        }}
        getTooltip={place => place.name}
        onClick={({ item }) => console.log(item)}
      />
    </MapContainer>
  );
}

Public coordinates use lon-lat order by default. Set coordinateOrder="lat-lon" on MapContainer if your application uses latitude first.

Data mapping

Bulk layers use conventional fields by default:

| Component | Default geometry field | | --- | --- | | PointLayer, ClusterLayer, WebGLPointLayer | item.position | | LineStringLayer, ArrowLineLayer | item.coordinates | | PolygonLayer | item.coordinates | | GeometryLayer | item.geometry |

Items use item.id as their feature ID. Domain models with different field names can be adapted with getId, getPosition, getCoordinates, or getGeometry without reshaping the source data.

<PointLayer
  id="vehicles"
  items={vehicles}
  getId={vehicle => vehicle.uuid}
  getPosition={vehicle => [vehicle.longitude, vehicle.latitude]}
  getTooltip={vehicle => vehicle.label}
/>

API overview

• Maps: MapContainer, MapProvider
• Vector layers: PointLayer, LineStringLayer, PolygonLayer, GeometryLayer, ArrowLineLayer
• Specialized layers: ClusterLayer, ClusterHtmlLayer, WebGLPointLayer
• Overlays: Overlay, HtmlMarker, StickyTooltip
• Interactions: DrawInteraction, ModifyInteraction, SelectInteraction, SnapInteraction, TranslateInteraction
• Hooks: useMap, useView, useLayer, useVectorSource, useInteraction, useMapActions
• View helpers: zoomViewToCoordinate, fitViewToCoordinates, fitViewToFeature, fitViewToFeatures
• Styling: createStyle, createPointStyle, createIconStyle, createTextStyle, style caches, and svgToDataUrl

See the documentation and live examples for component props and advanced usage.

Performance model

Each bulk layer owns a stable OpenLayers layer and source. Features are reconciled by ID, so unchanged features preserve their identity instead of being recreated on every React render. Revision getters and style keys are available for large or frequently updated datasets.

Map-level event listeners are shared between managed layers. Callback props remain current without repeatedly registering OpenLayers listeners.

OpenLayers access

The library does not hide OpenLayers. Use typed refs or useMap, useView, useLayer, useVectorSource, and useInteraction when an application needs lower-level APIs.

Development

npm install
npm run typecheck
npm run test
npm run build

Additional commands:

npm run playground
npm run playground:build
npm run benchmark

License

MIT