{"canonical_url":"https://engineer.company/glossary/leaflet/","content_markdown":"# Leaflet\n\n## What it is\n\nLeaflet is an open-source JavaScript library that turns one element on a web\npage into a map a person can pan, zoom and click. The project puts its size at\nabout 42 KB of JavaScript and lists no external dependencies. It was created by\nVolodymyr Agafonkin, is now developed by a community of contributors, and is\nreleased under the BSD 2-Clause licence.\n\nIts own overview says it does not try to do everything for everyone and\nconcentrates on making the basic things work well. `L.map` takes an element and\na set of options and becomes the map. A tile layer fetches square images from a\nURL template with `{z}`, `{x}` and `{y}` in it and lays them out as a grid of\nimage elements, and a WMS variant does the same against a Web Map Service.\nPolylines, polygons, circles and rectangles are drawn as SVG by default, or on a\nsingle canvas when the map is created with `preferCanvas`. Markers are icons,\neither an image or a plain `div`, with popups and tooltips attached. A GeoJSON\nlayer turns each feature into one of those layers, a point into a marker unless\ntold otherwise. Zoom buttons, attribution, a layer switcher and a scale bar make\nup the controls. The default coordinate reference system is EPSG:3857, which the\nreference calls the most common one for online maps.\n\nEverything past that list comes from plugins. The project's plugin database\ndescribes Leaflet as meant to be as lightweight as possible and points to\nhundreds of third-party plugins, sorted into groups such as vector tiles,\nclustering, heatmaps, geometry editing, routing and geocoding.\n\nTwo release lines exist at the time of writing. The stable one is 1.9.4,\nreleased on 18 May 2023, and the API reference on the project's site reflects\nit. The prerelease, 2.0.0-alpha.1 from 16 August 2025, drops support for\nInternet Explorer and ships as an ES module. It keeps the global `L` only in a\nbundled `leaflet-global.js`, replaces factory functions with constructors, so\nthat `L.marker(latlng)` becomes `new Marker(latlng)`, and takes input through\npointer events.\n\n## Why it matters\n\nPutting a map on a page is two decisions that are easy to mistake for one: which\ncode draws the map in the browser, and where the map imagery comes from. Leaflet\nkeeps them apart, and the choice to use it is mostly a choice to keep them\napart.\n\nLeaflet draws. The tiles come from wherever the URL template points, so the\nbasemap is a separate decision with its own price, terms and owner. It can be\nthe OpenStreetMap tile server while a feature is being built, a commercial\nprovider in production, a tile server the project runs itself, or a\nmunicipality's WMS through `TileLayer.WMS`. Moving between them changes a string\nand an attribution line, and the application code around the map stays as it is.\n\nThe size and the licence decide where Leaflet fits comfortably. About 42 KB and\nno dependencies suit a page where the map is one part among many: a form where\nsomeone drops a pin, or an admin screen that shows where records are. The BSD\n2-Clause licence puts no account, key or metering between the library and the\npage.\n\nThe price of a small core is that heavier features arrive as separate packages,\neach with its own maintainer and release pace, and a map that leans on six\nplugins inherits six upgrade paths. The 2.0 alpha shows what that means: its\nmigration notes point users of older plugins to a V1 polyfill, because those\nplugins expect the global `L` and the factory functions. A map that needs vector\ntiles styled in the browser at every zoom has a closer fit in a library built\naround them, a decision best made before six plugins hold the map up.\n\n## What it looks like in practice\n\nLeaflet appears on two pages of this site, both from the GIS Software\nDevelopment Team Lead role between 2015 and 2022, and on both it shares the\nfront end with Mapbox.\n\nThe role led\n[more than thirty GIS projects, built and then deployed](/portfolio/led-30-gis-projects-from-build-to-support/).\nOn the front of those projects were web maps built on Mapbox GL and Leaflet,\nsometimes against the ArcGIS or HERE APIs, with the app layer in JavaScript,\nPython, PHP and SQL. Underneath sat PostgreSQL with PostGIS, and GDAL/OGR moved\ndata between shapefiles, GeoJSON, GeoTIFF, KML and vector tiles. The\nresponsibility ran past shipping into support in production.\n\nThe same role also sat in\n[the design process for its projects' user interfaces](/portfolio/contributed-to-user-interface-design-processes/).\nThese were React, Angular and Vue front-ends sitting over Mapbox and Leaflet\nmaps, and the page makes a point worth keeping next to any map library: on a\nweb-map product the map is the easy part, and the controls, the filtering and\nthe flow around it are where people get lost. The usability lived in details\nsuch as how a dataset was filtered and how someone moved between floors on an\nindoor map, and the page credits most of the difference to asking those\nquestions during design rather than after release.\n\n## Where it goes wrong\n\nLeaflet is small enough that most of its failures come from the page around it,\nor from the services it is pointed at.\n\n**The map shows as a grey box or a strip of stray tiles.** Leaflet takes its\nsize from its container. The quick start lists two things to do before any map\ncode runs: include Leaflet's CSS file ahead of the JavaScript, and give the\ncontainer a defined height. A `div` with no height gives a map with no height. A\nsubtler case is a map created inside a tab or dialog that is hidden at the time:\nit measures itself at zero and keeps that size when it appears. Leaflet 1.x\nfollows the browser window resizing, through `trackResize`, so a container that\nchanges size on its own goes unnoticed until the code calls `invalidateSize()`,\nwhich the reference says to call after the map's size has changed. The 2.0 alpha\nuses `ResizeObserver` in place of the window's resize event.\n\n**Points turn up thousands of kilometres away.** GeoJSON, as RFC 7946 defines\nit, writes a position longitude first. Leaflet's `LatLng` and the arrays it\naccepts in its place are latitude first. `L.geoJSON` converts between the two on\nits own, so the bug appears when coordinates are lifted out of GeoJSON by hand\nand passed straight to a marker or a polyline. A point in Copenhagen, swapped,\nlands in the Arabian Sea. Unpack the pair by name at the boundary:\n\n```js\nconst res = await fetch(\"/api/sites/42\");\nconst site = await res.json();\nconst [lon, lat] = site.geometry.coordinates; // GeoJSON: lon, lat\nL.marker([lat, lon]).addTo(map); // Leaflet: lat, lng\n```\n\n**Panning stutters once the data grows.** With the SVG renderer each line or\npolygon is its own element in the document, and each default marker is its own\nimage. A layer of many thousand features means many thousand elements for the\nbrowser to move on every pan and zoom. `preferCanvas: true` draws paths on one\ncanvas, but it applies to paths only, so points have to become `L.circleMarker`,\na circle of fixed pixel radius that is itself a path, through the GeoJSON\nlayer's `pointToLayer` option. Past that point the answer is sending less: a\nclustering plugin, or an API that returns only what fits the current view and\nzoom.\n\n**Tiles stop loading after launch.** The quick start builds its first map on\nOpenStreetMap's tile server and says plainly that those tiles are fine for\nprogramming, but that the Tile Usage Policy is to be read before production. The\npolicy asks for visible attribution, a User-Agent that identifies the\napplication and a valid Referer from web pages, caching according to the HTTP\nheaders, and no bulk downloading or prefetching. It offers no service-level\nagreement and may block access without notice. A busy production map belongs on\na provider whose terms fit its traffic, or on its own tile server, and with\nLeaflet that move is the URL template and the attribution text.\n\n## Further reading\n\n- [Leaflet](https://leafletjs.com/) — the project's overview, feature list and a\n  first map in a few lines.\n- [Leaflet API reference](https://leafletjs.com/reference.html) — every class,\n  option and method in 1.9.4, including `preferCanvas`, `invalidateSize` and the\n  GeoJSON options.\n- [Leaflet Quick Start Guide](https://leafletjs.com/examples/quick-start/) — the\n  CSS, the container height and a first tile layer, step by step.\n- [Leaflet 2.0 Alpha released](https://leafletjs.com/2025/05/18/leaflet-2.0.0-alpha.html)\n  — what changes in 2.0 and how to migrate code and plugins.\n- [Tile Usage Policy](https://operations.osmfoundation.org/policies/tiles/) —\n  the conditions for using the openstreetmap.org tile servers.\n- [RFC 7946: The GeoJSON Format](https://www.rfc-editor.org/rfc/rfc7946) — the\n  GeoJSON standard, including the longitude-first order of positions.\n\n\u003chttps://engineer.company/glossary/leaflet/\u003e\n","date_modified":"2026-10-20T21:59:50Z","description":"How Leaflet turns a page element into a web map, what it leaves to tile providers and plugins, and the height, coordinate and tile-policy traps.","formats":{"gemtext":"https://engineer.company/glossary/leaflet/index.gmi","gopher":"https://engineer.company/glossary/leaflet/gophermap","html":"https://engineer.company/glossary/leaflet/","json":"https://engineer.company/glossary/leaflet/index.json","markdown":"https://engineer.company/glossary/leaflet/index.md","pdf":"https://engineer.company/glossary/leaflet/index.pdf"},"kind":"page","language":"en","title":"What is Leaflet?","url":"https://engineer.company/glossary/leaflet/","version":1}