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
- 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-latandlat-loncoordinate order support- Hooks and refs for direct access to OpenLayers maps, views, layers, sources, and interactions
npm install ol-react-kit ol react react-domThe 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';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.
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}
/>- 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, andsvgToDataUrl
See the documentation and live examples for component props and advanced usage.
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.
The library does not hide OpenLayers. Use typed refs or useMap, useView, useLayer, useVectorSource, and useInteraction when an application needs lower-level APIs.
npm install
npm run typecheck
npm run test
npm run buildAdditional commands:
npm run playground
npm run playground:build
npm run benchmark