{"id":11232,"library":"leaflet","title":"Leaflet","description":"Leaflet is a lightweight, open-source JavaScript library designed for creating mobile-friendly interactive maps. It focuses on performance, usability, and extensibility, providing a core set of features like layers, markers, popups, and controls, while supporting a rich ecosystem of plugins for advanced functionality. The current stable major version is 1.x, with `1.9.4` being the latest bugfix release, which is now in maintenance mode, receiving only critical bugfixes. Development has shifted significantly towards the upcoming 2.0 release, currently in alpha, which modernizes the codebase by dropping Internet Explorer support, removing legacy methods, and fully embracing ES Modules. Its simple API and strong community support make it a popular choice for web mapping applications, particularly where performance and bundle size are critical.","status":"maintenance","version":"1.9.4","language":"javascript","source_language":"en","source_url":"git://github.com/Leaflet/Leaflet","tags":["javascript","gis","map"],"install":[{"cmd":"npm install leaflet","lang":"bash","label":"npm"},{"cmd":"yarn add leaflet","lang":"bash","label":"yarn"},{"cmd":"pnpm add leaflet","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"In Leaflet 1.x, the library typically exposes a global `L` object. Direct named imports for `L` are not supported. For bundlers, `import 'leaflet'` makes `L` available globally or through `window.L`.","wrong":"import { L } from 'leaflet';","symbol":"L (global object)","correct":"import 'leaflet'; // Makes L globally available (v1.x)\n// or via script tag: <script src=\"leaflet.js\"></script>"},{"note":"Leaflet 2.x is fully ESM, meaning core components are named exports. The global `L` is no longer part of the core package but is available in the bundled `leaflet-global.js`.","wrong":"const L = require('leaflet'); L.map(...);","symbol":"Named exports (Map, tileLayer, marker)","correct":"import { Map, tileLayer, marker } from 'leaflet';"},{"note":"Due to compatibility issues with plugins, the default ESM entrypoint was removed from the `leaflet` package in `v1.9.2`. Users wanting ESM in 1.x must explicitly import this path.","wrong":"import 'leaflet';","symbol":"ESM explicit path (v1.9.2+)","correct":"import 'leaflet/dist/leaflet-src.esm.js';"},{"note":"For TypeScript with Leaflet 1.x, importing all as `L` is a common pattern when using bundlers, alongside `@types/leaflet` for type definitions.","symbol":"TypeScript types","correct":"import * as L from 'leaflet';\n// Ensure @types/leaflet is installed: npm install --save-dev @types/leaflet"}],"quickstart":{"code":"import 'leaflet/dist/leaflet.css'; // Essential for Leaflet styles\n\n// For TypeScript with bundlers and Leaflet 1.x, `import * as L from 'leaflet';` is common.\n// For native browser usage with script tags, `L` is globally available.\nimport * as L from 'leaflet';\n\n// A common issue in bundlers is that Leaflet's default marker icons aren't correctly resolved.\n// We override L.Icon.Default to point to known URLs, preventing missing marker images.\nL.Icon.Default.mergeOptions({\n  iconRetinaUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-icon-2x.png',\n  iconUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-icon.png',\n  shadowUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-shadow.png'\n});\n\ndocument.addEventListener('DOMContentLoaded', () => {\n  // Ensure a map div exists\n  let mapDiv = document.getElementById('map');\n  if (!mapDiv) {\n    mapDiv = document.createElement('div');\n    mapDiv.id = 'map';\n    mapDiv.style.height = '400px';\n    mapDiv.style.width = '100%';\n    document.body.appendChild(mapDiv);\n  }\n\n  // Initialize the map on the 'map' div with a given view and zoom level\n  const map = L.map('map').setView([51.505, -0.09], 13);\n\n  // Add an OpenStreetMap tile layer to the map\n  L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {\n    attribution: '&copy; <a href=\"http://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors'\n  }).addTo(map);\n\n  // Add a marker to the map at a specific coordinate\n  L.marker([51.5, -0.09])\n    .addTo(map)\n    .bindPopup('A sample marker in London!')\n    .openPopup();\n});","lang":"typescript","description":"This quickstart demonstrates how to initialize a basic Leaflet map, add an OpenStreetMap tile layer, and place a marker with a popup. It also addresses the common issue of missing marker icons when using bundlers."},"warnings":[{"fix":"Migrate imports to use named ES Module syntax (e.g., `import { Map, tileLayer } from 'leaflet';`). For users relying on the global `L`, consider using the bundled `leaflet-global.js` or adapting to named imports.","message":"Leaflet v2.0 introduces a full conversion to ES Modules, fundamentally changing how the library is imported. The global `L` object is no longer provided by the core package. Legacy CommonJS `require` is also no longer supported for the core.","severity":"breaking","affected_versions":">=2.0.0-alpha"},{"fix":"Ensure your target browser environment meets modern standards. Review custom plugins and code for reliance on deprecated Leaflet 1.x APIs or IE-specific logic.","message":"Leaflet v2.0 has dropped support for Internet Explorer and removed many legacy methods and polyfills, adopting modern web standards like Pointer Events. This may cause issues in older browser environments or with plugins relying on deprecated APIs.","severity":"breaking","affected_versions":">=2.0.0-alpha"},{"fix":"While 1.x remains stable, plan for eventual migration to Leaflet 2.x to benefit from ongoing development, modernizations, and new features.","message":"As of v1.9.0, the Leaflet 1.x branch has entered maintenance mode, meaning future releases will be reserved primarily for critical bugfixes. New features and significant development are focused on the 2.x branch.","severity":"gotcha","affected_versions":">=1.9.0"},{"fix":"If you need an ESM entrypoint in 1.x, explicitly import `leaflet/dist/leaflet-src.esm.js`. For most users with bundlers, `import 'leaflet'` or `require('leaflet')` might still resolve to the CJS or UMD bundle.","message":"The default ESM entrypoint was temporarily removed from the main package in v1.9.2 due to compatibility issues with plugins. Importing `leaflet` via ESM might not work as expected in some bundlers.","severity":"gotcha","affected_versions":">=1.9.2 <2.0.0"},{"fix":"Manually set `L.Icon.Default.mergeOptions` to point to absolute URLs for the icon images (e.g., from unpkg.com) or configure your bundler to copy and correctly resolve the images from `node_modules/leaflet/dist/images`.","message":"When using bundlers (like Webpack, Vite) with Leaflet 1.x, the default marker icons often fail to load because their paths are relative and not correctly handled by the bundler's asset pipeline.","severity":"gotcha","affected_versions":">=1.0.0 <2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For Leaflet 1.x, ensure `leaflet.js` is loaded via a `<script>` tag or `import 'leaflet'` is used in a bundler setup. For Leaflet 2.x, use named imports like `import { Map } from 'leaflet';` or ensure you are loading the `leaflet-global.js` bundle if you require the global `L`.","cause":"The Leaflet library was not properly loaded or imported, or you are trying to use `L` in a Leaflet 2.x ESM-only environment without the global bundle.","error":"ReferenceError: L is not defined"},{"fix":"Override Leaflet's default icon paths to point to absolute URLs (e.g., `L.Icon.Default.mergeOptions({ iconRetinaUrl: 'https://...', iconUrl: 'https://...', shadowUrl: 'https://...' });`) or configure your bundler to copy `node_modules/leaflet/dist/images` to your public asset folder.","cause":"Leaflet's default marker icons cannot be found by the browser, usually because a bundler hasn't correctly resolved the relative image paths from `node_modules`.","error":"TypeError: Cannot read properties of undefined (reading 'mergeOptions') OR Failed to load resource: the server responded with a status of 404 (Not Found) for marker images."},{"fix":"For Leaflet 1.x, rely on the global `L` object or `import * as L from 'leaflet';` in TypeScript. For Leaflet 2.x, ensure your build setup supports ES Modules and use named imports like `import { Map, tileLayer } from 'leaflet';`. If on Leaflet `v1.9.2` or later and explicitly want ESM, import `leaflet/dist/leaflet-src.esm.js`.","cause":"This can occur in Leaflet 1.x when attempting named imports that are not available, or in 2.x if the environment isn't correctly resolving ES Modules, or trying to use new ESM imports in a 1.x environment.","error":"Cannot find module 'leaflet' OR Attempted import error: 'Map' is not exported from 'leaflet'."}],"ecosystem":"npm"}