Leaflet: JavaScript Library for Interactive Maps

What Leaflet is

Leaflet is an open-source JavaScript library for interactive web maps. Its README calls it the leading open-source JavaScript library for building powerful interactive maps, and says it is designed with simplicity, performance and usability in mind. The pitch is a small core that handles the things nearly every map needs, such as panning and zooming a tiled basemap, dropping markers, drawing lines and polygons, showing popups and reacting to user input, while everything more specialised is left to a large plugin ecosystem.

The project was created in 2010 by Volodymyr Agafonkin, a Ukrainian developer living in Kyiv, and the homepage says it is now developed by a big community of contributors. The top of the README is a statement from the maintainers about Russia's invasion of Ukraine, noting that Leaflet is used for documenting war crimes, tracking the front line and finding humanitarian aid, and asking readers to support Ukrainian charities. The homepage says it powers maps on millions of websites.

An important framing point from the FAQ: Leaflet is just a JavaScript library. Unlike Google Maps and other all-in-one solutions, it does not provide map imagery on its own. You pair it with a tile service, either a commercial or community provider or tiles you render and host yourself. The library is provider-agnostic, and the quick-start guide stresses that it does not contain a single provider-specific line of code. That split between rendering library and data source shapes almost every adoption decision covered below.

It suits front-end developers building store locators or delivery-zone maps, data journalists plotting GeoJSON, and GIS teams publishing WMS layers to the browser. It is licensed under BSD-2-Clause and written in JavaScript.

Versions: 1.9.4 stable and the 2.0 beta

Leaflet is in the middle of a major version transition, and it matters which line you read about. According to the changelog, the last 1.x release is 1.9.4, published on 2023-05-18. Leaflet 2.0 began with an alpha in May 2025; 2.0.0-beta.1 followed on 2026-11-02 and 2.0.0-beta.2 on 2026-11-06. The package.json on the main branch reports version 2.0.0-beta.2.

The install page states it plainly: the current release is a beta of Leaflet 2.0, a modern rewrite with ES modules and classes, and npm install leaflet keeps installing 1.9.4 until 2.0.0 is out. If your app relies on plugins that do not support 2.0 yet, the docs recommend staying on 1.9.4. The 2.0 betas are installed explicitly with the beta tag.

The changelog summarises 2.0 as a major modernization of the codebase: Leaflet is published as ES modules with classes instead of factory functions, uses Pointer Events instead of separate mouse and touch events, and drops Internet Explorer and other legacy browsers along with a lot of compatibility code. Beta 1 added full tree-shaking, bundled TypeScript types and a default marker icon that works with any bundler; beta 2 added a fullscreen control and a translate option for built-in text. The rest of this write-up uses 2.0 class names when describing the API and points out where 1.x differs.

How Leaflet works

The map and its layers

Everything starts with a map instance bound to a div on the page. In 2.0 that is new LeafletMap('map'); the migration guide explains that Map is also exported but importing it would shadow JavaScript's built-in Map, so the docs use LeafletMap. You set a view (centre coordinates and a zoom level) and add layers to the map. The quick-start guide notes that most Leaflet methods return the object they were called on when they have nothing else to return, which allows method chaining such as new LeafletMap('map').setView([51.505, -0.09], 13).

Layers are the main building blocks. The homepage lists tile layers and WMS, markers, popups and tooltips, polylines, polygons, circles and rectangles, GeoJSON, and image, video and SVG overlays. A TileLayer is created from a URL template with {z}, {x} and {y} placeholders plus options such as maxZoom and attribution. LayerGroup bundles layers so they can be added or removed together, and the layers control switches between base layers and toggles overlays.

Panes and stacking

Under the hood, layers live in map panes. The map panes tutorial explains that panes group layers implicitly and use the CSS z-index property so some layers always draw on top of others. The default order runs from tile and grid layers at the bottom, through paths such as polylines, circles and GeoJSON, then marker shadows, marker icons, and popups on top. Custom panes, created with map.createPane(), let you change that order, for example to draw a labels-only tile layer above your GeoJSON.

Renderers: SVG or Canvas

Vector layers are drawn by a renderer. The homepage lists SVG or Canvas vectors, clipped and simplified on the fly, and the panes tutorial notes that paths using the same renderer are drawn together in one SVG or Canvas element. The FAQ says Leaflet generally handles heavy vector data well thanks to real-time clipping and simplification, but suggests switching the map's default renderer from SVG to Canvas with the renderer: new Canvas() option when you have many thousands of points. In 2.0 the old preferCanvas option is removed in favour of that form.

Events

Every object fires events. The quick-start guide describes subscribing with map.on('click', handler), where the handler receives an event object, for example one with a latlng property for the clicked location. Leaflet 2.0 listens to Pointer Events, which the migration guide says cover mouse, touch and pen with one set of events, so mousedown and friends become pointerdown and similar.

Key features

• Small footprint. The README says Leaflet weighs about 40 kB of gzipped JS plus 2.4 kB of gzipped CSS; the 2.0 beta 1 changelog says a tree-shaken map with a tile layer is 25.6 kB gzipped, down from 38 kB.
• Tile layers and WMS. Raster basemaps from any provider via URL templates, plus a WMSTileLayer for WMS services.
• Vector overlays. Markers, polylines, polygons, circles and rectangles, with style options such as colour, fill colour and opacity.
• GeoJSON support. The GeoJSON tutorial says Leaflet supports all RFC 7946 geometry types, with Features and FeatureCollections working best because their properties can drive styling and popups.
• Popups and tooltips. bindPopup() attaches HTML content to a layer, and standalone popups can be opened at any coordinate with openOn(map).
• Interaction. Panning with inertia, zoom with the wheel, pinch, double tap or shift-drag, the same behaviour for mouse, touch and pen, and draggable markers.
• Rendering. GPU-accelerated zoom and pan animations, sharp output on high-DPI screens, fractional zoom levels, and a map that follows the size of its container.
• Built-in controls. Zoom buttons, attribution, a layer switcher and a scale, plus an opt-in FullscreenControl added in 2.0 beta 2.
• Accessibility. Keyboard navigation of the map, markers and controls, labelled controls and alt text for screen readers.
• Developer ergonomics in 2.0. Tree-shakable ES modules, TypeScript types included in the package, and no dependencies, per the homepage feature list.

Getting started

For a bundler-based project, the install page gives the npm command for the 2.0 beta:

npm install leaflet@beta

Then import the classes you need and the stylesheet:

import {LeafletMap, TileLayer} from 'leaflet';
import 'leaflet/styles.css';

The quick-start guide then creates a map centred on London and adds an OpenStreetMap tile layer. The map container div needs an explicit height:

const map = new LeafletMap('map').setView([51.505, -0.09], 13);

new TileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
	maxZoom: 19,
	attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>'
}).addTo(map);

Adding a marker follows the same pattern (add Marker to the import list), and bindPopup() attaches content to it:

const marker = new Marker([51.5, -0.09]).addTo(map);

Without a build step, the quick-start and install pages load the ES module from a CDN using an import map, and leaflet-global.js is available as a classic script that exposes a global L. If you need to stay on 1.x, the install page provides 1.9.4 CDN tags with Subresource Integrity hashes:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/leaflet.css"
	integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY=" crossorigin="anonymous">
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/leaflet.js"
	integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo=" crossorigin="anonymous"></script>

Use cases

• Location features in web apps. Store finders, delivery or service-area maps and property listings: a tile layer, markers with popups and a few event handlers cover most of the work, which is the scenario the quick-start guide walks through.
• Publishing GIS data. GeoJSON layers with property-driven styling and popups, or WMS layers through WMSTileLayer, let teams put existing spatial data in front of users without a heavy client.
• Mobile map pages. The mobile tutorial builds a full-viewport map that zooms to the user's position with map.locate({setView: true, maxZoom: 16}) and shows accuracy as a circle.
• Non-geographic imagery. The homepage calls out non-geographical maps for floor plans, game maps and images, using a simple CRS instead of a web Mercator projection.
• Custom basemaps. The FAQ points to QGIS and gdal2tiles for rendering your own data into static tile images that any web server can host.
• Large point datasets. The FAQ recommends the Leaflet.markercluster plugin for thousands of markers and the Canvas renderer for heavy vector data, or pre-rendering into image tiles when the data is too large to draw client-side.

How it compares

The FAQ positions Leaflet against Google Maps and other all-in-one solutions: those bundle the library, the imagery and the billing, while Leaflet is a free library you combine with a tile service of your choice. The FAQ adds that Google's Map Tiles API can feed a TileLayer under Google's terms.

For vector tiles and WebGL-rendered maps, the plugins page has a "Vector tiles & GL maps" category for plugins that display vector tiles or add a MapLibre or Mapbox GL map to Leaflet as a layer. That is a useful signal: vector-tile and GL rendering are not part of the Leaflet core, and if your product depends on client-side styled vector tiles, rotation-heavy 3D views or GPU rendering of very large datasets, a GL-native library such as MapLibre GL JS is the more obvious candidate to evaluate. Other open-source web mapping libraries, OpenLayers being the best-known in the same category, are also worth a look if you need broader built-in GIS functionality; compare them against your own requirements rather than relying on generic feature lists.

The FAQ says the core is kept small and simple on purpose, leaving the rest to plugin authors. If your needs are a raster basemap with markers, shapes, GeoJSON and popups, that trade-off works in your favour; if they go well beyond it, you are choosing plugins as much as you are choosing Leaflet.

Things to know before adopting

Leaflet is not a tile source

The single most common misunderstanding is that Leaflet provides maps. It does not. You must pick a tile provider, and the FAQ is emphatic: always read the terms of use of the chosen provider, know its limitations and attribute it properly. The quick-start guide says OpenStreetMap tiles are fine while you are programming your map, but that you should read the OpenStreetMap Tile Usage Policy before using them in production, and that attribution is obligatory for anything based on OpenStreetMap. Commercial providers the FAQ lists, such as Mapbox, MapTiler and Esri ArcGIS, are free only up to a particular number of requests. The 2.0 changelog says http:// OpenStreetMap URLs are now upgraded to HTTPS, as the OSM tile policy requires.

Licensing

The code is BSD-2-Clause. The FAQ says commercial use is fine as long as you attribute the library somewhere, for example by keeping the Leaflet link on the map or mentioning it on an About page or in a README. That licence covers only the code; map imagery is governed by your tile provider's terms.

The 1.x to 2.0 transition

2.0 is still in beta, and it carries a long list of breaking changes. The migration guide lists loading Leaflet as an ES module (a plain <script> tag pointing at dist/leaflet.js now fails with a syntax error), removing the default export, replacing factory functions with constructors, flattening nested class names such as Control.Zoom to ZoomControl, and switching to pointer events:

// 1.x
const map = L.map('map');
L.marker([51.5, -0.09]).bindPopup('Hi').addTo(map);

// 2.0
const map = new LeafletMap('map');
new Marker([51.5, -0.09]).bindPopup('Hi').addTo(map);

The guide says most changes are loud, meaning a removed API throws or logs a message naming the replacement, but some are marked silent and need checking by hand. The 2.0 package also ships its own TypeScript types that replace @types/leaflet, with different type names, which affects typed codebases. Deep imports from leaflet/src/... or leaflet/dist/... no longer resolve, apart from the stylesheet.

Plugin compatibility and quality

Much of Leaflet's value comes from plugins, and the plugins page lists hundreds of them across categories from basemap providers to routing and geocoding. The ES module build does not define a global L, so the migration guide warns that plugins expecting window.L need a version that supports Leaflet 2 or the global build. Plugin authors are asked to mark compatible plugins so they appear in a "Ready for Leaflet 2" section, and the changelog points to Leaflet.markercluster and Leaflet.heat as examples ported to support both 1.9 and 2.0. Plugins are third-party code, and the accessibility guide warns that plugins can enhance the experience but can also degrade it, so test each one you add. Check maintenance status and 2.0 support before committing to a plugin-heavy design.

Browser support

Leaflet 2.0 targets Baseline 2022 browsers (Safari 15.4+). Internet Explorer and other legacy browsers are no longer supported, and VML rendering is gone. If you still serve very old browsers, 1.9.4 is the line that kept that compatibility code.

Security and CDN integrity

The quick-start guide warns that popup content is rendered as HTML, so you should not pass untrusted user input to it directly. The install page recommends keeping the Subresource Integrity hashes when copying CDN snippets, and notes that CDNs such as jsDelivr, unpkg and cdnjs are external services. The security policy asks reporters to use GitHub's private vulnerability reporting rather than public issues.

Accessibility

The map container and markers are keyboard operable by default. The accessibility guide says every marker needs a unique, descriptive alt or title to give it an accessible name and suggests hiding purely decorative maps from assistive technology with the HTML inert attribute.

Project activity

As of November 2026 the repository has about 45,900 stars and roughly 6,200 forks on GitHub. It was created in September 2010, is written in JavaScript, is licensed under BSD-2-Clause, and received commits as recently as November 2026. The changelog shows an active 2.0 cycle, with two betas released in the first week of November 2026, both carrying community contributions alongside work from the core maintainers. The beta 1 changelog says tests now run with Vitest in Chromium, Firefox and WebKit, and every pull request is checked for tree-shaking, bundle size, types and API changes.

The source is at github.com/Leaflet/Leaflet and the docs, tutorials, plugins list and API reference are at leafletjs.com. If you are upgrading an existing app, read the migration guide and the changelog first.