{"id":11230,"library":"leaflet-geometryutil","title":"Leaflet GeometryUtil","description":"Leaflet GeometryUtil is a utility library that extends Leaflet's core functionality with a wide array of geometric operations. It provides functions for calculating distances, bearings between points, interpolating points along polylines, locating points on lines, finding closest points or layers to a given geographic coordinate, rotating points around a center, and managing layers within a specified radius. The library seamlessly integrates with Leaflet's `L.LatLng` and layer objects, providing a cohesive API for complex geospatial computations directly within Leaflet applications. The current stable version is 0.10.3, released in December 2023, indicating active maintenance with several minor and patch releases per year to add features and address bugs. A key differentiator is its deep integration with the Leaflet ecosystem, offering a comprehensive set of geometric tools that feel native to Leaflet, rather than a standalone geometry library. It has included robust TypeScript definitions since version 0.10.0, significantly enhancing the developer experience for TypeScript projects by providing strong type checking and intellisense for all its utilities.","status":"active","version":"0.10.3","language":"javascript","source_language":"en","source_url":"https://github.com/makinacorpus/Leaflet.GeometryUtil","tags":["javascript","Leaflet","GIS","typescript"],"install":[{"cmd":"npm install leaflet-geometryutil","lang":"bash","label":"npm"},{"cmd":"yarn add leaflet-geometryutil","lang":"bash","label":"yarn"},{"cmd":"pnpm add leaflet-geometryutil","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for core Leaflet objects and map instance; the library extends Leaflet's functionality.","package":"leaflet","optional":false}],"imports":[{"note":"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.","wrong":"import { closest } from 'leaflet-geometryutil';","symbol":"GeometryUtil (ESM/TypeScript)","correct":"import L from 'leaflet';\nimport GeometryUtil from 'leaflet-geometryutil';"},{"note":"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.","wrong":"import { GeometryUtil } from 'leaflet';","symbol":"Global L.GeometryUtil (Side Effect Import)","correct":"import 'leaflet';\nimport 'leaflet-geometryutil';\n// Then use L.GeometryUtil.functionName(map, ...)"},{"note":"For CommonJS environments, `require()` directly returns the `L.GeometryUtil` object after `leaflet` has been loaded.","wrong":"const { closest } = require('leaflet-geometryutil');","symbol":"GeometryUtil (CommonJS)","correct":"const L = require('leaflet');\nconst GeometryUtil = require('leaflet-geometryutil');"}],"quickstart":{"code":"import L from 'leaflet';\nimport GeometryUtil from 'leaflet-geometryutil';\nimport 'leaflet/dist/leaflet.css';\n\n// Ensure you have a div with id=\"map\" in your HTML\n// <div id=\"map\" style=\"height: 400px; width: 600px;\"></div>\n\nconst map = L.map('map').setView([51.505, -0.09], 13);\nL.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {\n  attribution: '© OpenStreetMap contributors'\n}).addTo(map);\n\n// Define a polyline\nconst polylinePoints = [\n  [51.505, -0.09],\n  [51.51, -0.08],\n  [51.50, -0.05],\n  [51.515, -0.07]\n];\nconst polyline = L.polyline(polylinePoints, {color: 'blue'}).addTo(map);\n\n// Example 1: Find the closest point on the polyline to a given point\nconst testPoint = L.latLng(51.51, -0.10);\nL.marker(testPoint).addTo(map).bindPopup('Test Point').openPopup();\n\nconst closestPointResult = GeometryUtil.closest(map, polyline, testPoint);\nif (closestPointResult) {\n  L.marker(closestPointResult.latlng, {\n    icon: L.divIcon({ className: 'my-div-icon', html: 'Closest' })\n  }).addTo(map);\n  console.log('Closest point on polyline:', closestPointResult.latlng.toString());\n} else {\n  console.log('No closest point found (polyline might be empty).');\n}\n\n// Example 2: Interpolate a point on the line at 50% distance\nconst interpolatedPointResult = GeometryUtil.interpolateOnLine(map, polyline, 0.5);\nif (interpolatedPointResult) {\n  L.circleMarker(interpolatedPointResult.latlng, {\n    radius: 5,\n    color: 'red'\n  }).addTo(map).bindPopup('Interpolated Point (50%)');\n  console.log('Interpolated point on polyline:', interpolatedPointResult.latlng.toString());\n}","lang":"typescript","description":"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`."},"warnings":[{"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.","message":"Version 0.8.1 removed a deprecated function from Leaflet 1.x. Users relying on this function will experience a breaking change upon upgrade.","severity":"breaking","affected_versions":">=0.8.1"},{"fix":"Ensure Leaflet's script tag or module import executes before `leaflet-geometryutil` to ensure `L` is defined.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Upgrade to version 0.7.2 or newer to benefit from fixes ensuring deep copies and correct segment handling in `closest` method.","message":"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.","severity":"gotcha","affected_versions":"<0.7.2"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.10.2"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.10.3 (with Leaflet 2.0)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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>`.","cause":"`leaflet.js` or `leaflet` module was not loaded or imported before `leaflet-geometryutil`.","error":"ReferenceError: L is not defined"},{"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.","cause":"`leaflet-geometryutil` script or module was not loaded/imported, or `L.GeometryUtil` was not properly assigned/augmented.","error":"TypeError: L.GeometryUtil.closest is not a function"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'distanceTo')"}],"ecosystem":"npm"}