Leaflet GeometryUtil

Common errors

• ReferenceError: L is not defined

  cause `leaflet.js` or `leaflet` module was not loaded or imported before `leaflet-geometryutil`.
  fix Ensure `leaflet` is loaded globally via a script tag or imported as a module before `leaflet-geometryutil`. E.g., `import 'leaflet'; import 'leaflet-geometryutil';` or `<script src="leaflet.js"></script><script src="leaflet.geometryutil.js"></script>`.

• TypeError: L.GeometryUtil.closest is not a function

  cause `leaflet-geometryutil` script or module was not loaded/imported, or `L.GeometryUtil` was not properly assigned/augmented.
  fix Verify that `leaflet-geometryutil` is correctly included in your project. If using modules, ensure `import GeometryUtil from 'leaflet-geometryutil';` (or similar side-effect import) is present and executed.

• TypeError: Cannot read properties of undefined (reading 'distanceTo')

  cause Often occurs when `map.latLngToLayerPoint` is called with an invalid map object or `latLngToLayerPoint` itself is undefined, usually because the map object is not initialized or passed correctly to `GeometryUtil` functions.
  fix Ensure that the `map` object passed as the first argument to `GeometryUtil` functions (e.g., `GeometryUtil.closest(map, ...)` or `GeometryUtil.distance(map, ...)`) is a valid and initialized `L.Map` instance.

Warnings

• breaking Version 0.8.1 removed a deprecated function from Leaflet 1.x. Users relying on this function will experience a breaking change upon upgrade.
  Fix: Review your code for usage of deprecated Leaflet 1.x functions and replace them with modern Leaflet APIs or alternative `leaflet-geometryutil` methods if applicable.
• gotcha Leaflet must be loaded and available globally (as `L`) or properly imported before `leaflet-geometryutil` is used, especially in browser environments without a module bundler. The library extends the `L` object directly.
  Fix: Ensure Leaflet's script tag or module import executes before `leaflet-geometryutil` to ensure `L` is defined.
• gotcha The `closest` method previously used shallow copies for `latLngs` and had issues with the last segment on Polygons or nested Polygons in versions prior to 0.7.2. While fixed, be aware of potential subtle geometry calculation discrepancies if using older versions.
  Fix: Upgrade to version 0.7.2 or newer to benefit from fixes ensuring deep copies and correct segment handling in `closest` method.
• gotcha Version 0.10.2 included changes to imports to accommodate `ngx-leaflet` organization. While this might primarily affect `ngx-leaflet` users, it highlights that specific module environments or custom bundling setups might need adjustment if relying on implicit import side-effects.
  Fix: If experiencing import issues in `ngx-leaflet` or similar environments, consult the `ngx-leaflet` documentation or `leaflet-geometryutil`'s source for specific import patterns used in `v0.10.2`.
• breaking Leaflet 2.0 (currently in alpha, targeting stable November 2025) removes the global `L` object and replaces factory methods with constructors. `leaflet-geometryutil` heavily relies on augmenting `L`. This future change will likely break `leaflet-geometryutil` in its current form and require significant updates.
  Fix: Monitor `leaflet-geometryutil` for updates to support Leaflet 2.0. If upgrading Leaflet to 2.0, ensure `leaflet-geometryutil` has a compatible version or seek alternatives that support the new Leaflet architecture.

Install

• npm install leaflet-geometryutil npm
• yarn add leaflet-geometryutil yarn
• pnpm add leaflet-geometryutil pnpm

Imports

• GeometryUtil (ESM/TypeScript)
  wrong:

  import { closest } from 'leaflet-geometryutil';

  correct:

  import L from 'leaflet';
  import GeometryUtil from 'leaflet-geometryutil';

  The library exports the `L.GeometryUtil` object as its default module export. Individual named exports are not available. This pattern is suitable for bundlers like Webpack or Rollup.
• Global L.GeometryUtil (Side Effect Import)
  wrong:

  import { GeometryUtil } from 'leaflet';

  correct:

  import 'leaflet';
  import 'leaflet-geometryutil';
  // Then use L.GeometryUtil.functionName(map, ...)

  When used in environments where Leaflet is globally available (e.g., via script tags or in module systems that manage global augmentation), importing `leaflet-geometryutil` as a side effect augments the global `L` object, making utilities available via `L.GeometryUtil`. This is a common pattern for Leaflet plugins.
• GeometryUtil (CommonJS)
  wrong:

  const { closest } = require('leaflet-geometryutil');

  correct:

  const L = require('leaflet');
  const GeometryUtil = require('leaflet-geometryutil');

  For CommonJS environments, `require()` directly returns the `L.GeometryUtil` object after `leaflet` has been loaded.

Quickstart

Initializes a Leaflet map, adds a polyline, then demonstrates finding the closest point on that polyline to a given `L.LatLng` and interpolating a point at 50% along the line's length using `GeometryUtil.closest` and `GeometryUtil.interpolateOnLine`.

import L from 'leaflet';
import GeometryUtil from 'leaflet-geometryutil';
import 'leaflet/dist/leaflet.css';

// Ensure you have a div with id="map" in your HTML
// <div id="map" style="height: 400px; width: 600px;"></div>

const map = L.map('map').setView([51.505, -0.09], 13);
L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
  attribution: '© OpenStreetMap contributors'
}).addTo(map);

// Define a polyline
const polylinePoints = [
  [51.505, -0.09],
  [51.51, -0.08],
  [51.50, -0.05],
  [51.515, -0.07]
];
const polyline = L.polyline(polylinePoints, {color: 'blue'}).addTo(map);

// Example 1: Find the closest point on the polyline to a given point
const testPoint = L.latLng(51.51, -0.10);
L.marker(testPoint).addTo(map).bindPopup('Test Point').openPopup();

const closestPointResult = GeometryUtil.closest(map, polyline, testPoint);
if (closestPointResult) {
  L.marker(closestPointResult.latlng, {
    icon: L.divIcon({ className: 'my-div-icon', html: 'Closest' })
  }).addTo(map);
  console.log('Closest point on polyline:', closestPointResult.latlng.toString());
} else {
  console.log('No closest point found (polyline might be empty).');
}

// Example 2: Interpolate a point on the line at 50% distance
const interpolatedPointResult = GeometryUtil.interpolateOnLine(map, polyline, 0.5);
if (interpolatedPointResult) {
  L.circleMarker(interpolatedPointResult.latlng, {
    radius: 5,
    color: 'red'
  }).addTo(map).bindPopup('Interpolated Point (50%)');
  console.log('Interpolated point on polyline:', interpolatedPointResult.latlng.toString());
}