Declarative mapping components
npm install @planet/maps
See the planetlabs.github.io/maps website for more details and examples using the library.
React lets you build interactive UIs with (mostly) declarative syntax. OpenLayers provides an imperative API for building mapping apps. It can be awkward to map React's component API to an imperative API. However, the React team provides a package for creating custom renderers:
react-reconciler. This is how they integrate with imperative APIs themselves. The
react-dom package uses
react-reconciler to provide a mapping to the imperative DOM API.
react-reconciler to map to imperative native APIs.
This library provides declarative mapping components representing imperative APIs from OpenLayers.
The purpose of this project is to provide a mapping between React's declarative components and OpenLayers' imperative API. In other words, this project provides a React renderer for OpenLayers.
Here are some of the goals of this project:
- Ideally, the renderer would not have any additional dependencies beyond what is bundled with an OpenLayers map.
- Components exported by this package map 1:1 with classes exported by OpenLayers.
- Component props map directly to properties that are settable on instances of OpenLayers classes. Exceptions to this are props like
options(passed to the constructor only), listener props (e.g.
- Components accept a
refthat provide access to the underlying OpenLayers instance.
- The renderer should add negligible overhead in terms of bundle size, memory consumption, or processing.
- Code components can be generated by using OpenLayers sources. Exceptions to this are the map component (responsible for invoking the custom renderer) and components that map to classes without subclasses (e.g. the view).
This project does not intend to provide any of the following:
- Higher level abstractions or components that combine logic from multiple OpenLayers instances (e.g. an editable layer component that wraps a layer, source, and editing interactions).
- Styled widgets (e.g. a layer switcher/browser).
- Other utilities for working with vector data, projections, etc.
We hope that this package can provide the foundation for other, higher-level libraries with more opinions about the look and feel of mapping components.
The development setup depends on Node 18 (most things work on 16, but not all).
Install project dependencies:
Start the development server:
Run the tests:
The rendering tests use Playwright for visual snapshot comparison. See the
tests/rendering/readme.md for more detail.
Other projects like
react-ol-fiber use a similar approach and provided inspiration for this project. The major difference between this project and those is that this project provides importable components for OpenLayers layers, sources, controls, and interactions. The other projects bundle all of OpenLayers in their renderer. So a simple "hello world" map with one of the existing projects is about 1.5 MB while the same with this project is about 460 KB.