FAQ.md

Leaflet FAQ

This is a collection of answers to the most frequently asked questions about Leaflet.

1. Data Providers
2. Commercial Use and Licensing
3. Features
4. Performance
5. Misc

Data Providers

The map is wrong in my neighborhood, could you fix it?

Nope, but you can. The map you see on Leaflet examples is based on OpenStreetMap, a free editable map of the world. Signing up and editing the map there is easy, and the changes will be reflected on the map in a few minutes.

What map tiles can I use with Leaflet? Is it limited to OpenStreetMap?

Leaflet is provider-agnostic, meaning you can use any map provider as long as you conform to its terms of use. You can roll your own tiles as well. OpenStreetMap is the most popular data source among different tile providers, but there are providers that use other sources.

Check out this example with over seventy different layers to choose from. Popular commercial options, free up to a particular number of requests, include MapBox, Bing Maps (using a plugin), Esri ArcGIS (official plugin), MapQuest (official plugins) and Here Maps.

Always be sure to read the terms of use of a chosen tile provider, know its limitations, and attribute it properly in your app.

I'm looking for satellite imagery to use with my Leaflet map, any options?

MapBox, Bing Maps, ArcGIS and MapQuest Open provide satellite imagery among others.

I want to use Google Maps API tiles with Leaflet, can I do that?

The problem with Google is that its Terms of Use forbid any means of tile access other than through the Google Maps API.

You can add the Google Maps API as a Leaflet layer with the GoogleMutant plugin. But note that the map experience will not be perfect, because Leaflet must wait for the Google Maps JS engine to load the map tiles, so you might experience glitches and lagging when using it.

I want to roll my own OSM tile server for Leaflet, where do I start?

Check out this excellent guide.

I want to create tiles from my own data for use with Leaflet, what are the options?

There's a number of services that allow you to do this easily, notably MapBox, CartoDB and GIS Cloud. If you want to make tiles on your own, probably the easiest way is using TileMill. TileMill can export your map as a single .mbtiles file, which can be copied to a webserver and accessed by Leaflet with a small PHP script. Alternatively, you can extract the tiled images from the .mbtiles database and place them directly on your webserver with absolutely no server-side dependencies.

Commercial Use and Licensing

I have an app that gets lots of hits a day, and I want to switch from Google/Bing/whatever to Leaflet. Is there a fee for using it?

Leaflet, unlike Google Maps and other all-in-one solutions, is just a JavaScript library. It's free to use, but doesn't provide map imagery on its own — you have to choose a tile service to combine with it.

There are plenty of options for a tile service, each with their own terms of use, prices (some of them free), features, limitations, etc. Choice is yours.

I'm building a commercial app that I plan to sell. Can I use Leaflet in it?

You're welcome, as the code is published under the very permissive 2-clause BSD License. Just make sure to attribute the use of the library somewhere in the app UI or the distribution (e.g. keep the Leaflet link on the map, or mention the use on the About page or a Readme file, etc.) and you'll be fine.

That only applies to the code though. Make sure you conform to the terms of use of the tile images provider(s) that you choose as well.

Features

What's the best way to put the data I have on a Leaflet map?

Check out this awesome cheatsheet.

Why is there still no feature X in Leaflet?

First of all, did you check out the Leaflet plugins page? It lists about a hundred plugins doing all kinds of crazy stuff, and there's a high possibility that it has what you're looking for.

Generally, we do our best to keep the Leaflet core small, lightweight and simple, focusing on quality instead of quantity, and leaving all the rest to plugin authors.

Check out this video of a talk by the Leaflet creator for more background on the story and philosophy behind Leaflet. Another essential read is Advocating Simplicity in Open Source by the same guy.

Performance

I have thousands of markers on my map. How do I make it faster and more usable?

Check out the Leaflet.markercluster plugin. It's amazing.

I have vector data with many thousands of points on my map. Any performance tips?

Leaflet generally does a pretty good job of handling heavy vector data with its real-time clipping and simplification algorithms, but browser technology still has its limits. Try switching from SVG to Canvas as the default rendering back-end, it may help considerably (depends on the app and the data).

If you still have too much data to render, you'll have to use some help of a server-side service like MapBox, CartoDB and GIS Cloud (they all work great with Leaflet). What they do under the hood is serving rendered data as image tiles, along with additional data to enable interactivity like hovering shapes (e.g. done using UTFGrid — Leaflet has a nice plugin for it).

Misc

I downloaded the Leaflet source but didn't find leaflet.js there. Why is that?

You can download the built versions using links from the download page. It even includes the latest build of the development version (master branch), updated automatically on each commit to the repo.

We removed the built versions from the repository because it's a chore to build and commit them manually on each change, and it often complicates merging branches and managing contributions.

There's a common complaint that Leaflet can't be used with Bower because of that, but we'll resolve the issue soon.