Map

The central class of the API — it is used to create a map on a page and manipulate it.

Usage example

// initialize the map on the "map" div with a given center and zoom
var map = L.map('map', {
	center: [51.505, -0.09],
	zoom: 13
});

Creation

Options

Map State Options

Interaction Options

Keyboard Navigation Options

Panning Inertia Options

Control options

Animation options

Events

You can subscribe to the following events using these methods.

Methods for Modifying Map State

Methods for Getting Map State

Methods for Layers and Controls

Conversion Methods

Other Methods

Locate options

Zoom/pan options

Pan options

Zoom options

fitBounds options

The same as zoom/pan options and additionally:

Properties

Map properties include interaction handlers that allow you to control interaction behavior in runtime, enabling or disabling certain features such as dragging or touch zoom (see IHandler methods). Example:

map.doubleClickZoom.disable();

You can also access default map controls like attribution control through map properties:

map.attributionControl.addAttribution("Earthquake data © GeoNames");

Map Panes

An object literal (returned by map.getPanes) that contains different map panes that you can use to put your custom overlays in. The difference is mostly in zIndex order that such overlays get.

Marker

Used to put markers on the map.

L.marker([50.5, 30.5]).addTo(map);

Creation

Options

Events

You can subscribe to the following events using these methods.

Methods

Interaction handlers

Interaction handlers are properties of a marker instance that allow you to control interaction behavior in runtime, enabling or disabling certain features such as dragging (see IHandler methods). Example:

marker.dragging.disable();

Popup

Used to open popups in certain places of the map. Use Map#openPopup to open popups while making sure that only one popup is open at one time (recommended for usability), or use Map#addLayer to open as many as you want.

Usage example

If you want to just bind a popup to marker click and then open it, it's really easy:

marker.bindPopup(popupContent).openPopup();

Path overlays like polylines also have a bindPopup method. Here's a more complicated way to open a popup on a map:

var popup = L.popup()
	.setLatLng(latlng)
	.setContent('<p>Hello world!<br />This is a nice popup.</p>')
	.openOn(map);

Creation

Options

Methods

TileLayer

Used to load and display tile layers on the map, implements ILayer interface.

Usage example

L.tileLayer('http://{s}.tile.cloudmade.com/{key}/{styleId}/256/{z}/{x}/{y}.png', {
	key: 'API-key',
	styleId: 997
}).addTo(map);

Creation

URL template

A string of the following form:

'http://{s}.somedomain.com/blabla/{z}/{x}/{y}.png'

{s} means one of the available subdomains (used sequentially to help with browser parallel requests per domain limitation; subdomain values are specified in options; a, b or c by default, can be omitted), {z} — zoom level, {x} and {y} — tile coordinates.

You can use custom keys in the template, which will be evaluated from TileLayer options, like this:

L.tileLayer('http://{s}.somedomain.com/{foo}/{z}/{x}/{y}.png', {foo: 'bar'});

Options

Events

You can subscribe to the following events using these methods.

Methods

TileLayer.WMS

Used to display WMS services as tile layers on the map. Extends TileLayer.

Usage example

var nexrad = L.tileLayer.wms("http://mesonet.agron.iastate.edu/cgi-bin/wms/nexrad/n0r.cgi", {
	layers: 'nexrad-n0r-900913',
	format: 'image/png',
	transparent: true,
	attribution: "Weather data © 2012 IEM Nexrad"
});

Creation

Options

Includes all TileLayer options and additionally:

Methods

TileLayer.Canvas

Used to create Canvas-based tile layers where tiles get drawn on the browser side. Extends TileLayer.

Usage example

var canvasTiles = L.tileLayer.canvas();

canvasTiles.drawTile = function(canvas, tilePoint, zoom) {
	var ctx = canvas.getContext('2d');
	// draw something on the tile canvas
}

Creation

Options

Methods

ImageOverlay

Used to load and display a single image over specific bounds of the map, implements ILayer interface.

Usage example

var imageUrl = 'http://www.lib.utexas.edu/maps/historical/newark_nj_1922.jpg',
	imageBounds = [[40.712216, -74.22655], [40.773941, -74.12544]];

L.imageOverlay(imageUrl, imageBounds).addTo(map);

Creation

Options

Methods

Path

An abstract class that contains options and constants shared between vector overlays (Polygon, Polyline, Circle). Do not use it directly.

Options

Events

You can subscribe to the following events using these methods.

Methods

Static properties

Polyline

A class for drawing polyline overlays on a map. Extends Path. Use Map#addLayer to add it to the map.

Usage example

// create a red polyline from an arrays of LatLng points
var polyline = L.polyline(latlngs, {color: 'red'}).addTo(map);

// zoom the map to the polyline
map.fitBounds(polyline.getBounds());

Creation

Options

You can use Path options and additionally the following options:

Methods

You can use Path methods and additionally the following methods:

MultiPolyline

Extends FeatureGroup to allow creating multi-polylines (single layer that consists of several polylines that share styling/popup).

Creation

Methods

MultiPolylines accept all Polyline methods but have different behavior around their coordinate contents since they can contain multiple line features:

Polygon

A class for drawing polygon overlays on a map. Extends Polyline. Use Map#addLayer to add it to the map.

Note that points you pass when creating a polygon shouldn't have an additional last point equal to the first one — it's better to filter out such points.

Creation

Methods

Polygon has the same options and methods as Polyline, with the following differences:

MultiPolygon

Extends FeatureGroup to allow creating multi-polygons (single layer that consists of several polygons that share styling/popup).

Creation

Methods

MultiPolygons accept all Polyline methods but have different behavior around their coordinate contents since they can contain multiple polygon features:

Rectangle

A class for drawing rectangle overlays on a map. Extends Polygon. Use Map#addLayer to add it to the map.

Usage example

// define rectangle geographical bounds
var bounds = [[54.559322, -5.767822], [56.1210604, -3.021240]];

// create an orange rectangle
L.rectangle(bounds, {color: "#ff7800", weight: 1}).addTo(map);

// zoom the map to the rectangle bounds
map.fitBounds(bounds);

Creation

Methods

You can use Path methods and additionally the following methods:

Circle

A class for drawing circle overlays on a map. Extends Path. Use Map#addLayer to add it to the map.

L.circle([50.5, 30.5], 200).addTo(map);

Creation

Methods

CircleMarker

A circle of a fixed size with radius specified in pixels. Extends Circle. Use Map#addLayer to add it to the map.

Creation

Methods

LayerGroup

Used to group several layers and handle them as one. If you add it to the map, any layers added or removed from the group will be added/removed on the map as well. Implements ILayer interface.

L.layerGroup([marker1, marker2])
	.addLayer(polyline)
	.addTo(map);

Creation

Methods

group.eachLayer(function (layer) {
	layer.bindPopup('Hello');
});

FeatureGroup

Extended layerGroup that also has mouse events (propagated from members of the group) and a shared bindPopup method. Implements ILayer interface.

L.featureGroup([marker1, marker2, polyline])
	.bindPopup('Hello world!')
	.on('click', function() { alert('Clicked on a group!'); })
	.addTo(map);

Creation

Methods

Has all layerGroup methods and additionally:

Events

You can subscribe to the following events using these methods.

GeoJson

Represents a GeoJSON layer. Allows you to parse GeoJSON data and display it on the map. Extends FeatureGroup.

L.geoJson(data, {
	style: function (feature) {
		return {color: feature.properties.color};
	},
	onEachFeature: function (feature, layer) {
		layer.bindPopup(feature.properties.description);
	}
}).addTo(map);

Each feature layer created by it gets a feature property that links to the GeoJSON feature data the layer was created from (so that you can access its properties later).

Creation

Options

Additionally accepts all Path options for polylines and polygons.

Methods

Static methods

LatLng

Represents a geographical point with a certain latitude and longitude.

var latlng = L.latLng(50.5, 30.5);

All Leaflet methods that accept LatLng objects also accept them in a simple Array form and simple object form (unless noted otherwise), so these lines are equivalent:

map.panTo([50, 30]);
map.panTo({lon: 30, lat: 50});
map.panTo({lat: 50, lng: 30});
map.panTo(L.latLng(50, 30));

Creation

Properties

Methods

Constants

LatLngBounds

Represents a rectangular geographical area on a map.

var southWest = L.latLng(40.712, -74.227),
	northEast = L.latLng(40.774, -74.125),
	bounds = L.latLngBounds(southWest, northEast);

All Leaflet methods that accept LatLngBounds objects also accept them in a simple Array form (unless noted otherwise), so the bounds example above can be passed like this:

map.fitBounds([
	[40.712, -74.227],
	[40.774, -74.125]
]);

Creation

Methods

Point

Represents a point with x and y coordinates in pixels.

var point = L.point(200, 300);

All Leaflet methods and options that accept Point objects also accept them in a simple Array form (unless noted otherwise), so these lines are equivalent:

map.panBy([200, 300]);
map.panBy(L.point(200, 300));

Creation

Properties

Methods

Bounds

Represents a rectangular area in pixel coordinates.

var p1 = L.point(10, 10),
	p2 = L.point(40, 60),
	bounds = L.bounds(p1, p2);

All Leaflet methods that accept Bounds objects also accept them in a simple Array form (unless noted otherwise), so the bounds example above can be passed like this:

otherBounds.intersects([[10, 10], [40, 60]]);

Creation

Properties

Methods

Icon

Represents an icon to provide when creating a marker.

var myIcon = L.icon({
	iconUrl: 'my-icon.png',
	iconRetinaUrl: 'my-icon@2x.png',
	iconSize: [38, 95],
	iconAnchor: [22, 94],
	popupAnchor: [-3, -76],
	shadowUrl: 'my-icon-shadow.png',
	shadowRetinaUrl: 'my-icon-shadow@2x.png',
	shadowSize: [68, 95],
	shadowAnchor: [22, 94]
});

L.marker([50.505, 30.57], {icon: myIcon}).addTo(map);

L.Icon.Default extends L.Icon and is the blue icon Leaflet uses for markers by default.

Creation

Options

DivIcon

Represents a lightweight icon for markers that uses a simple div element instead of an image.

var myIcon = L.divIcon({className: 'my-div-icon'});
// you can set .my-div-icon styles in CSS

L.marker([50.505, 30.57], {icon: myIcon}).addTo(map);

By default, it has a 'leaflet-div-icon' class and is styled as a little white square with a shadow.

Creation

Options

Control

The base class for all Leaflet controls. Implements IControl interface. You can add controls to the map like this:

control.addTo(map);
// the same as
map.addControl(control);

Creation

Options

Methods

Control Positions

Control positions (map corner to put a control to) are set using strings. Margins between controls and the map border are set with CSS, so that you can easily override them.

Control.zoom

A basic zoom control with two buttons (zoom in and zoom out). It is put on the map by default unless you set its zoomControl option to false. Extends Control.

Creation

Options

Control.Attribution

The attribution control allows you to display attribution data in a small text box on a map. It is put on the map by default unless you set its attributionControl option to false, and it fetches attribution texts from layers with getAttribution method automatically. Extends Control.

Creation

Options

Methods

Control.Layers

The layers control gives users the ability to switch between different base layers and switch overlays on/off (check out the detailed example). Extends Control.

var baseLayers = {
	"CloudMade": cloudmade,
	"OpenStreetMap": osm
};

var overlays = {
	"Marker": marker,
	"Roads": roadsLayer
};

L.control.layers(baseLayers, overlays).addTo(map);

Creation

Methods

Options

Layer Config

An object literal with layer names as keys and layer objects as values:

{
	"<someName1>": layer1,
	"<someName2>": layer2
}

The layer names can contain HTML, which allows you to add additional styling to the items:

{"<img src='my-layer-icon' /> <span class='my-layer-item'>My Layer</span>": myLayer}

Events

You can subscribe to the following events on the Map object using these methods.

Control.Scale

A simple scale control that shows the scale of the current center of screen in metric (m/km) and imperial (mi/ft) systems. Extends Control.

L.control.scale().addTo(map);

Creation

Options

Events methods

A set of methods shared between event-powered classes (like Map). Generally, events allow you to execute some function when something happens with an object (e.g. the user clicks on the map, causing the map 'fire' event).

Example

map.on('click', function(e) {
	alert(e.latlng);
});

Leaflet deals with event listeners by reference, so if you want to add a listener and then remove it, define it as a function:

function onClick(e) { ... }

map.on('click', onClick);
map.off('click', onClick);

Methods

Event objects

Event object is an object that you recieve as an argument in a listener function when some event is fired, containing useful information about that event. For example:

map.on('click', function(e) {
	alert(e.latlng); // e is an event object (MouseEvent in this case)
});

Event

The base event object. All other event objects contain these properties too.

MouseEvent

LocationEvent

ErrorEvent

LayerEvent

LayersControlEvent

TileEvent

ResizeEvent

GeoJSON event

Popup event

DragEndEvent

Class

L.Class powers the OOP facilities of Leaflet and is used to create almost all of the Leaflet classes documented here.

In addition to implementing a simple classical inheritance model, it introduces several special properties for convenient code organization — options, includes and statics.

var MyClass = L.Class.extend({
	initialize: function (greeter) {
		this.greeter = greeter;
		// class constructor
	},

	greet: function (name) {
		alert(this.greeter + ', ' + name)
	}
});

// create instance of MyClass, passing "Hello" to the constructor
var a = new MyClass("Hello");

// call greet method, alerting "Hello, World"
a.greet("World");

Class Factories

You may have noticed that Leaflet objects are created without using the new keyword. This is achieved by complementing each class with a lowercase factory method:

new L.Map('map'); // becomes:
L.map('map');

The factories are implemented very easily, and you can do this for your own classes:

L.map = function (id, options) {
	return new L.Map(id, options);
};

Inheritance

You use L.Class.extend to define new classes, but you can use the same method on any class to inherit from it:

var MyChildClass = MyClass.extend({
	// ... new properties and methods
});

This will create a class that inherits all methods and properties of the parent class (through a proper prototype chain), adding or overriding the ones you pass to extend. It will also properly react to instanceof:

var a = new MyChildClass();
a instanceof MyChildClass; // true
a instanceof MyClass; // true

You can call parent methods (including constructor) from corresponding child ones (as you do with super calls in other languages) by accessing parent class prototype and using JavaScript's call or apply:

var MyChildClass = MyClass.extend({
	initialize: function () {
		MyClass.prototype.initialize.call("Yo");
	},

	greet: function (name) {
		MyClass.prototype.greet.call(this, 'bro ' + name + '!');
	}
});

var a = new MyChildClass();
a.greet('Jason'); // alerts "Yo, bro Jason!"

Options

options is a special property that unlike other objects that you pass to extend will be merged with the parent one instead of overriding it completely, which makes managing configuration of objects and default values convenient:

var MyClass = L.Class.extend({
	options: {
		myOption1: 'foo',
		myOption2: 'bar'
	}
});

var MyChildClass = L.Class.extend({
	options: {
		myOption1: 'baz',
		myOption3: 5
	}
});

var a = new MyChildClass();
a.options.myOption1; // 'baz'
a.options.myOption2; // 'bar'
a.options.myOption3; // 5

There's also L.Util.setOptions, a method for conveniently merging options passed to constructor with the defauls defines in the class:

var MyClass = L.Class.extend({
	options: {
		foo: 'bar',
		bla: 5
	},

	initialize: function (options) {
		L.Util.setOptions(this, options);
		...
	}
});

var a = new MyClass({bla: 10});
a.options; // {foo: 'bar', bla: 10}

Includes

includes is a special class property that merges all specified objects into the class (such objects are called mixins). A good example of this is L.Mixin.Events that event-related methods like on, off and fire to the class.

 var MyMixin = {
	foo: function () { ... },
	bar: 5
};

var MyClass = L.Class.extend({
	includes: MyMixin
});

var a = new MyClass();
a.foo();

You can also do such includes in runtime with the include method:

MyClass.include(MyMixin);

Statics

statics is just a convenience property that injects specified object properties as the static properties of the class, useful for defining constants:

var MyClass = L.Class.extend({
	statics: {
		FOO: 'bar',
		BLA: 5
	}
});

MyClass.FOO; // 'bar'

Constructor Hooks

If you're a plugin developer, you often need to add additional initialization code to existing classes (e.g. editing hooks for L.Polyline). Leaflet comes with a way to do it easily using the addInitHook method:

MyClass.addInitHook(function () {
	// ... do something in constructor additionally
	// e.g. add event listeners, set custom properties etc.
});

You can also use the following shortcut when you just need to make one additional method call:

MyClass.addInitHook('methodName', arg1, arg2, …);

Browser

A namespace with properties for browser/feature detection used by Leaflet internally.

if (L.Browser.ie6) {
	alert('Upgrade your browser, dude!');
}

Util

Various utility functions, used by Leaflet internally.

Methods

Properties

Transformation

Represents an affine transformation: a set of coefficients a, b, c, d for transforming a point of a form (x, y) into (a*x + b, c*y + d) and doing the reverse. Used by Leaflet in its projections code.

var transformation = new L.Transformation(2, 5, -1, 10),
	p = L.point(1, 2),
	p2 = transformation.transform(p), //  L.point(7, 8)
	p3 = transformation.untransform(p2); //  L.point(1, 2)

Creation

Methods

LineUtil

Various utility functions for polyine points processing, used by Leaflet internally to make polylines lightning-fast.

Methods

PolyUtil

Various utility functions for polygon geometries.

Methods

DomEvent

Utility functions to work with the DOM events, used by Leaflet internally.

Methods

L.DomEvent.addListener(div, 'click', function (e) {
	L.DomEvent.stopPropagation(e);
});

DomUtil

Utility functions to work with the DOM tree, used by Leaflet internally.

Methods

Properties

PosAnimation

Used internally for panning animations, utilizing CSS3 Transitions for modern browsers and a timer fallback for IE6-9.

var fx = new L.PosAnimation();
fx.run(el, [300, 500], 0.5);

Creation

Methods

Events

You can subscribe to the following events using these methods.

Draggable

A class for making DOM elements draggable (including touch support). Used internally for map and marker dragging. Only works for elements that were positioned with DomUtil#setPosition

var draggable = new L.Draggable(elementToDrag);
draggable.enable();

Creation

Events

You can subscribe to the following events using these methods.

Methods

IHandler

An interface implemented by interaction handlers.

ILayer

Represents an object attached to a particular location (or a set of locations) on a map. Implemented by tile layers, markers, popups, image overlays, vector layers and layer groups.

Methods

Implementing Custom Layers

The most important things know about when implementing custom layers are Map viewreset event and latLngToLayerPoint method. viewreset is fired when the map needs to reposition its layers (e.g. on zoom), and latLngToLayerPoint is used to get coordinates for the layer's new position.

Another event often used in layer implementations is moveend which fires after any movement of the map (panning, zooming, etc.).

Another thing to note is that you'll usually need to add leaflet-zoom-hide class to the DOM elements you create for the layer so that it hides during zoom animation. Implementing zoom animation for custom layers is a complex topic and will be documented separately in future, but meanwhile you can take a look at how it's done for Leaflet layers (e.g. ImageOverlay) in the source.

Custom Layer Example

Here's how a custom layer implementation usually looks:

var MyCustomLayer = L.Class.extend({

	initialize: function (latlng) {
		// save position of the layer or any options from the constructor
		this._latlng = latlng;
	},

	onAdd: function (map) {
		this._map = map;

		// create a DOM element and put it into one of the map panes
		this._el = L.DomUtil.create('div', 'my-custom-layer leaflet-zoom-hide');
		map.getPanes().overlayPane.appendChild(this._el);

		// add a viewreset event listener for updating layer's position, do the latter
		map.on('viewreset', this._reset, this);
		this._reset();
	},

	onRemove: function (map) {
		// remove layer's DOM elements and listeners
		map.getPanes().overlayPane.removeChild(this._el);
		map.off('viewreset', this._reset, this);
	},

	_reset: function () {
		// update layer's position
		var pos = this._map.latLngToLayerPoint(this._latlng);
		L.DomUtil.setPosition(this._el, pos);
	}
});

map.addLayer(new MyCustomLayer(latlng));

IControl

Represents a UI element in one of the corners of the map. Implemented by zoom, attribution, scale and layers controls.

Methods

Every control in Leaflet should extend from Control class and additionally have the following methods:

Custom Control Example

var MyControl = L.Control.extend({
	options: {
		position: 'topright'
	},

	onAdd: function (map) {
		// create the control container with a particular class name
		var container = L.DomUtil.create('div', 'my-custom-control');

		// ... initialize other DOM elements, add listeners, etc.

		return container;
	}
});

map.addControl(new MyControl());

If specify your own constructor for the control, you'll also probably want to process options properly:

var MyControl = L.Control.extend({
	initialize: function (foo, options) {
		// ...
		L.Util.setOptions(this, options);
	},
	// ...
});

This will allow you to pass options like position when creating the control instances:

map.addControl(new MyControl('bar', {position: 'bottomleft'}));

IProjection

An object with methods for projecting geographical coordinates of the world onto a flat surface (and back). See Map projection.

Methods

Defined Projections

Leaflet comes with a set of already defined projections out of the box:

ICRS

Defines coordinate reference systems for projecting geographical points into pixel (screen) coordinates and back (and to coordinates in other units for WMS services). See Spatial reference system.

Methods

Properties

Defined CRS

Leaflet comes with a set of already defined CRS to use out of the box:

If you want to use some obscure CRS not listed here, take a look at the Proj4Leaflet plugin.

Global Switches

Global switches are created for rare cases and generally make Leaflet to not detect a particular browser feature even if it's there. You need to set the switch as a global variable to true before including Leaflet on the page, like this:

<script>L_PREFER_CANVAS = true;</script>
<script src="leaflet.js"></script>

noConflict

This method restores the L global variable to the original value it had before Leaflet inclusion, and returns the real Leaflet namespace so you can put it elsewhere, like this:

// L points to some other library
...
// you include Leaflet, it replaces the L variable to Leaflet namespace

var Leaflet = L.noConflict();
// now L points to that other library again, and you can use Leaflet.Map etc.

version

A constant that represents the Leaflet version in use.

L.version // returns "0.5" (or whatever version is currently in use)