@havforsk/react-ol

A React library for OpenLayers maps integration.

Installation

Install the package via npm:

npm install @havforsk/react-ol

Import the OpenLayers CSS styles by adding the following import to your main CSS file or directly in your React component:

@import 'ol/ol.css';

import 'ol/ol.css';

Usage

All maps start with the <MapProvider> component, which provides a map context that all other components hook into.

Inside the <MapProvider> component, you must have a <View> component that sets the map's view.

To actually render the map, you must have a <MapElement> component that renders a div that will contain the map.

Basic Example

import React from 'react';
import { MapProvider, MapElement, View } from '@havforsk/react-ol';
import { Layers, OSMTile } from '@havforsk/react-ol/layer';
import { Interactions, NoRotation } from '@havforsk/react-ol/interaction';
import 'ol/ol.css';

const App = () => {
  return (
    <MapProvider>
      <View center={[5, 60]} zoom={10} />
      <MapElement className="w-full h-full" />
      <Layers>
        <OSMTile />
      </Layers>
      <Interactions>
        <NoRotation /> {/* Disables accidental rotation on mobiles */}
      </Interactions>
    </MapProvider>
  );
}

export default App;

API Reference

Table of Contents

• Core Components
  • MapProvider
  • MapElement
  • View
• Hooks
  • useMap()
  • useZoom()
  • useConstant(initializer)
• Layers
  • Layers
  • OSMTile
  • TileLayer
  • VectorLayer
  • ImageLayer
  • WMSImageLayer
• Controls
  • Controls
  • ScaleLine
  • MousePosition
• Interactions
  • Interactions
  • NoRotation
• Events
  • MapEvent
  • ViewEvent
• Other Components
  • Overlay
  • RemoveDefaultZoomControl
  • MapContext

Core Components

MapProvider

Creates and provides an OpenLayers map object via context. This is the root of the map.

Props: Accepts all OpenLayers Map options

<MapProvider>
  {/* Map components go here */}
</MapProvider>

MapElement

Creates a div element that will contain the map. Use only one per map.

Props: Accepts all standard HTML div attributes except children

<MapElement className="w-full h-full" />

View

Sets the view of the map. Use only one per map.

Props: Accepts all OpenLayers View options

<View center={[5, 60]} zoom={10} />

Hooks

useMap()

Gets the OpenLayers map object from the context.

Returns: The OpenLayers Map instance

Throws: Error if not used within a MapProvider

const map = useMap();

useZoom()

Gets the current zoom level of the map. Note that this one will fire rapidly when zooming, potentially causing a lot of rerenders

Returns: The current zoom level as a number

Throws: Error if not used within a MapProvider or if the map doesn't have a view

const zoom = useZoom();

useConstant(initializer)

Creates a value with an initializer that is guaranteed to be the same for the lifetime of the component.

Parameters:

• initializer: Function to call to initialize the value (called only on first render)

Returns: The value returned from the initializer

const map = useConstant(() => new Map(options));

Layers

Import from @havforsk/react-ol/layer

Layers

Component for grouping layers together. It's simply a named React.Fragment.

<Layers>
  <OSMTile />
  <VectorLayer source={vectorSource} />
</Layers>

OSMTile

An OpenLayers OSM tile layer.

Props:

• osmOptions: Options passed to the OSM constructor
• All other props are passed to TileLayer

<OSMTile />

TileLayer

An OpenLayers tile layer.

Props: Accepts all OpenLayers TileLayer options

<TileLayer source={tileSource} opacity={0.5} />

VectorLayer

An OpenLayers vector layer.

Props: Accepts all OpenLayers VectorLayer options

<VectorLayer source={vectorSource} style={styleFunction} />

ImageLayer

An OpenLayers image layer.

Props: Accepts all OpenLayers ImageLayer options

<ImageLayer source={imageSource} />

WMSImageLayer

An OpenLayers WMS image layer.

Props:

• url: WMS source URL (required)
• wmsOptions: Options passed to the ImageWMS constructor
• All other props are passed to ImageLayer

<WMSImageLayer
  url="https://example.com/wms"
  wmsOptions={{ params: { LAYERS: 'layer_name' } }}
/>

Controls

Import from @havforsk/react-ol/control

Controls

Component for grouping controls together. It's simply a named React.Fragment.

<Controls>
  <ScaleLine />
  <MousePosition />
</Controls>

ScaleLine

Adds a scale line control to the map.

Props: Accepts all OpenLayers ScaleLine options plus:

• suppressWarning: Set to true to suppress className usage warning

<ScaleLine />

MousePosition

Displays the mouse position coordinates on the map.

Props: Accepts all OpenLayers MousePosition options

<MousePosition coordinateFormat={format} />

Interactions

Import from @havforsk/react-ol/interaction

Interactions

Component for grouping interactions together. It's simply a named React.Fragment.

<Interactions>
  <NoRotation />
</Interactions>

NoRotation

Removes the pinch-rotate interaction from the map. Useful for preventing accidental rotation on mobile devices. This is a custom component; it does not wrap an OpenLayers interaction.

<NoRotation />

Events

Import from @havforsk/react-ol/events

MapEvent

Attaches an event listener to the map.

Props:

• type: Event type string
• listener: Event handler function

<MapEvent type="click" listener={(e) => console.log(e.coordinate)} />

ViewEvent

Attaches an event listener to the map's view.

Props:

• type: Event type string
• listener: Event handler function that receives the event and view

<ViewEvent type="change:center" listener={(e, view) => console.log(view.getCenter())} />

Other Components

Overlay

Creates an OpenLayers overlay for displaying React components at specific map coordinates.

Props: Accepts all OpenLayers Overlay options except element, plus:

• children: React content to render in the overlay

<Overlay position={[5, 60]}>
  <div>Marker content</div>
</Overlay>

RemoveDefaultZoomControl

Removes the default zoom controls from the map. The controls are restored when the component unmounts.

<RemoveDefaultZoomControl />

MapContext

React context that provides the map instance. Typically you'll use the useMap hook instead of accessing this directly.

Development

Components in this library should take at least the same props as the options for the OpenLayers class they wrap, possibly more. These props are used to initialize the OpenLayers object using the useConstant hook, which ensures the object is only created once for the lifetime of the component.

Any changes to the props dynamically update the OpenLayers object by iterating over the props and applying changes using the object's .get and .set methods inside a useEffect hook.

See the source code files in the project for examples of this pattern in use.

Components should be put at a path similar to the path of the OpenLayers class they wrap.