Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GeometryUtil (ESM/TypeScript)
✓ import L from 'leaflet';
import GeometryUtil from 'leaflet-geometryutil';
✗ import { closest } 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)
✓ import 'leaflet';
import 'leaflet-geometryutil';
// Then use L.GeometryUtil.functionName(map, ...)
✗ import { GeometryUtil } from 'leaflet';
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)
✓ const L = require('leaflet');
const GeometryUtil = require('leaflet-geometryutil');
✗ const { closest } = require('leaflet-geometryutil');
For CommonJS environments, `require()` directly returns the `L.GeometryUtil` object after `leaflet` has been loaded.
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());
}
Debug
Known issues
breakingVersion 0.8.1 removed a deprecated function from Leaflet 1.x. Users relying on this function will experience a breaking change upon upgrade.fixReview your code for usage of deprecated Leaflet 1.x functions and replace them with modern Leaflet APIs or alternative `leaflet-geometryutil` methods if applicable.
affects: >=0.8.1
gotchaLeaflet 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.fixEnsure Leaflet's script tag or module import executes before `leaflet-geometryutil` to ensure `L` is defined.
affects: >=0.0.1
gotchaThe `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.fixUpgrade to version 0.7.2 or newer to benefit from fixes ensuring deep copies and correct segment handling in `closest` method.
affects: <0.7.2
gotchaVersion 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.fixIf 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`.
affects: >=0.10.2
breakingLeaflet 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.fixMonitor `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.
affects: >=0.10.3 (with Leaflet 2.0)
Errors
Common errors & fixes
ReferenceError: L is not defined
`leaflet.js` or `leaflet` module was not loaded or imported before `leaflet-geometryutil`.
fixEnsure `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
`leaflet-geometryutil` script or module was not loaded/imported, or `L.GeometryUtil` was not properly assigned/augmented.
fixVerify 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')
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.
fixEnsure 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.
Audit
Dependencies
leafletrequiredRequired for core Leaflet objects and map instance; the library extends Leaflet's functionality.