Leaflet

A Modern, Lightweight Open-Source JavaScript Library for Interactive Maps by CloudMade

Leaflet Quick Start Guide

This step-by-step guide will quickly get you started on Leaflet basics, including setting up a Leaflet map, working with markers, polylines and popups, and dealing with events.

View example on a separate page →

Preparing your page

Before writing any code for the map, you need to do the following preparation steps on your page:

Include Leaflet CSS files in the head section of your document:

<link rel="stylesheet" href="leaflet/leaflet.css" />
<!--[if lte IE 8]><link rel="stylesheet" href="leaflet/leaflet.ie.css" /><![endif]-->

Include Leaflet JavaScript file somewhere on the page (preferably before body close tag):
```
<script src="leaflet/leaflet.js"></script>
```
Put a div element with a certain id where you want your map to be and make sure it has defined width and height:
```
<div id="map" style="height: 200px"></div> 
```

Now you're ready to initialize the map and do some stuff with it.

Setting up the map

Let's create a map instance, set its view to the center of London and add a pretty CloudMade tile layer to it. First we'll initialize the map:

var map = new L.Map('map');

By default (as we didn't pass any options when creating the map instance), all mouse and touch interactions on the map are enabled, and it has zoom and attribution controls.

Next we'll create a tile layer to add to our map, in this case it's a CloudMade tile layer with Pale Dawn style. Creating a tile layer usually involves setting the URL template for the tile images (get yours at CloudMade), the attribution text and the maximum zoom level of the layer:

var cloudmadeUrl = 'http://{s}.tile.cloudmade.com/YOUR-API-KEY/997/256/{z}/{x}/{y}.png',
	cloudmadeAttrib = 'Map data &copy; 2011 OpenStreetMap contributors, Imagery &copy; 2011 CloudMade',
    cloudmade = new L.TileLayer(cloudmadeUrl, {maxZoom: 18, attribution: cloudmadeAttrib});

Finally we'll set the map view to the center of London at 13th zoom level and add our tile layer (see the resulting map above):

var london = new L.LatLng(51.505, -0.09); // geographical point (longitude and latitude)
map.setView(london, 13).addLayer(cloudmade);

Make sure this code is below both the map div and leaflet.js inclusion, or in a window.load or document.ready event handler.

Markers, circles and polygons

Besides tile layers, you can easily add other things to your map, including markers, polylines, polygons, circles, and popups. Let's add a marker:

var markerLocation = new L.LatLng(51.5, -0.09);

var marker = new L.Marker(markerLocation);
map.addLayer(marker);

Adding a circle is the same, but lets configure it by passing options as a third argument when creating the object (the second argument is the radius in pixels):

var circleLocation = new L.LatLng(51.508, -0.11),
	circleOptions = {
		color: 'red', 
		fillColor: '#f03', 
		fillOpacity: 0.5
	};
	
var circle = new L.Circle(circleLocation, 20, circleOptions);
map.addLayer(circle);

Add a polygon is easy too:

var p1 = new L.LatLng(51.509, -0.08),
	p2 = new L.LatLng(51.503, -0.06),
	p3 = new L.LatLng(51.51, -0.047),
	polygonPoints = [p1, p2, p3];

var polygon = new L.Polygon(polygonPoints);
map.addLayer(polygon);

Working with popups

Popups are usually used when you want to attach some information to a particular object on a map. Leaflet has a very handy shortcut for this:

marker.bindPopup("<b>Hello world!</b><br />I am a popup.").openPopup();
circle.bindPopup("I am a circle.");
polygon.bindPopup("I am a polygon.");

Try clicking on our objects. The bindPopup method attaches a popup with the specified HTML content to your marker so the popup appears when you click on the object, and the openPopup method (for markers only) immediately opens the attached popup.

You can also use popups as layers (when you need something more than attching a popup to an object):

var popup = new L.Popup();

popup.setLatLng(new L.LatLng(51.5, -0.09));
popup.setContent("I am a standalone popup.");
		
map.openPopup(popup);

Here we use openPopup instead of addLayer because it handles automatic closing of a previously opened popup when opening a new one which is good for usability.

Dealing with events

Every time something happens in Leaflet, e.g. user clicks on a marker or map zoom changes, the corresponding object sends an event which you can subscribe to with a function. It allows you to react to user interaction:

map.on('click', onMapClick);
		
function onMapClick(e) {
	alert("You clicked the map at " + e.latlng);
}

Each object has its own set of events — see documentation for details. The first argument of the listener function is an event object — it contains useful information about the event that happened. For example, map click event object (e in the example above) has latlng property which is a location at which the click occured.

Lets improve our example by using a popup instead of an alert and formatting the location string:

map.on('click', onMapClick);
		
var popup = new L.Popup();
		
function onMapClick(e) {
	var latlngStr = '(' + e.latlng.lat.toFixed(3) + ', ' + e.latlng.lng.toFixed(3) + ')';
			
	popup.setLatLng(e.latlng);
	popup.setContent("You clicked the map at " + latlngStr);
	
	map.openPopup(popup);
}

Try clicking on the first map on this page and you will see the coordinates in a popup.

Now you've learned Leaflet basics and can start building map apps straight away! Don't forget to take a look at the detailed documentation or other examples.