React OpenLayers Choropleth

A lightweight React component for creating interactive choropleth maps using OpenLayers. Create beautiful, responsive geographic visualizations with customizable color scales, interactive tooltips, and dynamic legends. Built with TypeScript and modern React practices.

Installation

npm install react-ol-choropleth

Basic Usage

import { ChoroplethMap } from "react-ol-choropleth";
import "react-ol-choropleth/style.css";

function App() {
  const geoData = {
    type: "FeatureCollection",
    features: [
      // Your GeoJSON features with properties like id, name, value
    ],
  };

  return (
    <ChoroplethMap
      // Required props
      data={geoData}
      valueProperty="population" // Property name in your GeoJSON features
      // Color scale configuration
      colorScale={{
        type: "sequential", // 'sequential' | 'diverging' | 'categorical'
        colors: ["#feedde", "#fdbe85", "#fd8d3c", "#e6550d", "#a63603"],
      }}
      // Map configuration
      zoom={4}
      baseMap="osm" // 'osm' | 'satellite' | 'none'
      // Legend configuration
      showLegend={true}
      legendPosition="top-right" // 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
      // Interaction options
      zoomToFeature={true}
      selectedFeatureBorderColor="#0099ff" // Color for highlighting selected/hovered features
      canZoomOutBoundaries={true} // Whether to allow zooming beyond data boundaries
      // Custom overlay configuration (optional)
      overlayOptions={{
        // When to show the overlay: 'click' or 'hover'
        trigger: "click",
        // Custom render function (optional)
        render: (feature) => (
          <div>
            <h3>{feature.get("name")}</h3>
            <p>Population: {feature.get("population").toLocaleString()}</p>
          </div>
        ),
        // If render is not provided, it will show all feature properties by default
        autoPan: true, // Auto pan map to show overlay when feature is clicked/hovered
      }}
      // Event handlers
      onFeatureClick={(feature, coordinate) => {
        if (feature) {
          console.log("Clicked:", {
            name: feature.get("name"),
            value: feature.get("population"),
            coordinate,
          });
        }
      }}
      onFeatureHover={(feature) => {
        if (feature) {
          console.log("Hovering:", feature.get("name"));
        }
      }}
    />
  );
}

Props

| Prop | Type | Description | Default | | ---------------------------- | ------------------------------------------------------------------- | -------------------------------------------- | ------------- | | data | GeoJSON \| Feature[] | GeoJSON data or array of OpenLayers features | - | | valueProperty | string | Property name to use for coloring features | - | | colorScale | ColorScale | Color scale configuration | - | | zoom | number | Initial zoom level | 2 | | showLegend | boolean | Whether to show the legend | true | | legendPosition | LegendPosition | Legend position | "top-right" | | baseMap | "osm" \| "satellite" \| "none" | Base map layer type | "osm" | | zoomToFeature | boolean | Auto-zoom on feature click | false | | selectedFeatureBorderColor | string | Selected/hovered feature highlight color | "#0099ff" | | canZoomOutBoundaries | boolean | Allow zooming beyond data boundaries | true | | overlayOptions | OverlayOptions \| false | Custom overlay configuration | See below | | onFeatureClick | (feature: Feature \| null, coordinate?: [number, number]) => void | Click event handler | - | | onFeatureHover | (feature: Feature \| null) => void | Hover event handler | - |

Default Overlay Options

{
  render: undefined, // Will show all feature properties if not provided
  trigger: "click", // "click" or "hover"
  autoPan: true,
}

Feature Highlighting

Features can be highlighted in two ways:

1. On click - Selected features get a 3px border with the selectedFeatureBorderColor
2. On hover - Hovered features get a 2px border with the same selectedFeatureBorderColor

The overlay display is controlled by the overlayOptions.trigger property, which can be set to either "click" or "hover".

Demo

Check out the live demo to see it in action.

License

MIT © Abdulrhman El-Saed