Leaflet

an open-source JavaScript library
for mobile-friendly interactive maps

API Reference


This reference reflects Leaflet 1.0.

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

Factory Description
L.map( <HTMLElement|String> id, <Map options> options? ) Instantiates a map object given a div element (or its id) and optionally an object literal with map options described below.

Options

Map State Options

Option Type Default Description
center LatLng null Initial geographical center of the map.
zoom Number null Initial map zoom.
layers ILayer[] null Layers that will be added to the map initially.
minZoom Number null Minimum zoom level of the map. Overrides any minZoom set on map layers.
maxZoom Number null Maximum zoom level of the map. This overrides any maxZoom set on map layers.
maxBounds LatLngBounds null When this option is set, the map restricts the view to the given geographical bounds, bouncing the user back when he tries to pan outside the view. To set the restriction dynamically, use setMaxBounds method.
maxBoundsViscosity Number 0.0 If maxBounds is set, this options will control how solid the bounds are when dragging the map around. The default value of 0.0 allows the user to drag outside the bounds at normal speed, higher values will slow down map dragging outside bounds, and 1.0 makes the bounds fully solid, preventing the user from dragging outside the bounds.
crs CRS L.CRS.
EPSG3857
Coordinate Reference System to use. Don't change this if you're not sure what it means.
renderer Renderer depends The default method for drawing vector layers on the map. L.SVG or L.Canvas by default depending on browser support.

Interaction Options

Option Type Default Description
dragging Boolean true Whether the map be draggable with mouse/touch or not.
touchZoom Boolean true Whether the map can be zoomed by touch-dragging with two fingers. If passed 'center', it will zoom to the center of the view regardless of where the touch events (fingers) were.
scrollWheelZoom Boolean true Whether the map can be zoomed by using the mouse wheel. If passed 'center', it will zoom to the center of the view regardless of where the mouse was.
wheelDebounceTime Number 40 Limits the rate at which a wheel can fire (in milliseconds). By default user can't zoom via wheel more often than once per 40 ms.
doubleClickZoom Boolean true Whether the map can be zoomed in by double clicking on it and zoomed out by double clicking while holding shift. If passed 'center', double-click zoom will zoom to the center of the view regardless of where the mouse was.
boxZoom Boolean true Whether the map can be zoomed to a rectangular area specified by dragging the mouse while pressing shift.
tap Boolean true Enables mobile hacks for supporting instant taps (fixing 200ms click delay on iOS/Android) and touch holds (fired as contextmenu events).
tapTolerance Number 15 The max number of pixels a user can shift his finger during touch for it to be considered a valid tap.
trackResize Boolean true Whether the map automatically handles browser window resize to update itself.
worldCopyJump Boolean false With this option enabled, the map tracks when you pan to another "copy" of the world and seamlessly jumps to the original one so that all overlays like markers and vector layers are still visible.
closePopupOnClick Boolean true Set it to false if you don't want popups to close when user clicks the map.
bounceAtZoomLimits Boolean true Set it to false if you don't want the map to zoom beyond min/max zoom and then bounce back when pinch-zooming.

Keyboard Navigation Options

Option Type Default Description
keyboard Boolean true Makes the map focusable and allows users to navigate the map with keyboard arrows and +/- keys.
keyboardPanOffset Number 80 Amount of pixels to pan when pressing an arrow key.
keyboardZoomOffset Number 1 Number of zoom levels to change when pressing + or - key.

Panning Inertia Options

Option Type Default Description
inertia Boolean true If enabled, panning of the map will have an inertia effect where the map builds momentum while dragging and continues moving in the same direction for some time. Feels especially nice on touch devices.
inertiaDeceleration Number 3000 The rate with which the inertial movement slows down, in pixels/second2.
inertiaMaxSpeed Number 1500 Max speed of the inertial movement, in pixels/second.
inertiaThreshold Number depends Number of milliseconds that should pass between stopping the movement and releasing the mouse or touch to prevent inertial movement. 32 for touch devices and 14 for the rest by default.

Control options

Option Type Default Description
zoomControl Boolean true Whether the zoom control is added to the map by default.
attributionControl Boolean true Whether the attribution control is added to the map by default.

Animation options

Option Type Default Description
fadeAnimation Boolean depends Whether the tile fade animation is enabled. By default it's enabled in all browsers that support CSS3 Transitions except Android.
zoomAnimation Boolean depends Whether the tile zoom animation is enabled. By default it's enabled in all browsers that support CSS3 Transitions except Android.
zoomAnimationThreshold Number 4 Won't animate zoom if the zoom difference exceeds this value.
markerZoomAnimation Boolean depends Whether markers animate their zoom with the zoom animation, if disabled they will disappear for the length of the animation. By default it's enabled in all browsers that support CSS3 Transitions except Android.

Events

You can subscribe to the following events using these methods.

Event Data Description
click MouseEvent Fired when the user clicks (or taps) the map.
dblclick MouseEvent Fired when the user double-clicks (or double-taps) the map.
mousedown MouseEvent Fired when the user pushes the mouse button on the map.
mouseup MouseEvent Fired when the user releases the mouse button on the map.
mouseover MouseEvent Fired when the mouse enters the map.
mouseout MouseEvent Fired when the mouse leaves the map.
mousemove MouseEvent Fired while the mouse moves over the map.
contextmenu MouseEvent Fired when the user pushes the right mouse button on the map, prevents default browser context menu from showing if there are listeners on this event. Also fired on mobile when the user holds a single touch for a second (also called long press).
focus Event Fired when the user focuses the map either by tabbing to it or clicking/panning.
blur Event Fired when the map loses focus.
preclick MouseEvent Fired before mouse click on the map (sometimes useful when you want something to happen on click before any existing click handlers start running).
load Event Fired when the map is initialized (when its center and zoom are set for the first time).
unload Event Fired when the map is destroyed with remove method.
viewreset Event Fired when the map needs to redraw its content (this usually happens on map zoom or load). Very useful for creating custom overlays.
movestart Event Fired when the view of the map starts changing (e.g. user starts dragging the map).
move Event Fired on any movement of the map view.
moveend Event Fired when the view of the map stops changing (e.g. user stopped dragging the map).
dragstart Event Fired when the user starts dragging the map.
drag Event Fired repeatedly while the user drags the map.
dragend DragEndEvent Fired when the user stops dragging the map.
zoomstart Event Fired when the map zoom is about to change (e.g. before zoom animation).
zoomend Event Fired when the map zoom changes.
zoomlevelschange Event Fired when the number of zoomlevels on the map is changed due to adding or removing a layer.
resize ResizeEvent Fired when the map is resized.
autopanstart Event Fired when the map starts autopanning when opening a popup.
layeradd LayerEvent Fired when a new layer is added to the map.
layerremove LayerEvent Fired when some layer is removed from the map.
baselayerchange LayerEvent Fired when the base layer is changed through the layer control.
overlayadd LayerEvent Fired when an overlay is selected through the layer control.
overlayremove LayerEvent Fired when an overlay is deselected through the layer control.
locationfound LocationEvent Fired when geolocation (using the locate method) went successfully.
locationerror ErrorEvent Fired when geolocation (using the locate method) failed.
popupopen PopupEvent Fired when a popup is opened (using openPopup method).
popupclose PopupEvent Fired when a popup is closed (using closePopup method).

Methods for Modifying Map State

Method Returns Description
setView( <LatLng> center, <Number> zoom?, <zoom/pan options> options? ) this Sets the view of the map (geographical center and zoom) with the given animation options.
setZoom( <Number> zoom, <zoom options> options? ) this Sets the zoom of the map.
zoomIn( <Number> delta?, <zoom options> options? ) this Increases the zoom of the map by delta (1 by default).
zoomOut( <Number> delta?, <zoom options> options? ) this Decreases the zoom of the map by delta (1 by default).
setZoomAround( <LatLng> latlng, <Number> zoom, <zoom options> options? ) this Zooms the map while keeping a specified point on the map stationary (e.g. used internally for scroll zoom and double-click zoom).
fitBounds( <LatLngBounds> bounds, <fitBounds options> options? ) this Sets a map view that contains the given geographical bounds with the maximum zoom level possible.
fitWorld( <fitBounds options> options? ) this Sets a map view that mostly contains the whole world with the maximum zoom level possible.
panTo( <LatLng> latlng, <pan options> options? ) this Pans the map to a given center. Makes an animated pan if new center is not more than one screen away from the current one.
panInsideBounds( <LatLngBounds> bounds, <pan options> options? ) this Pans the map to the closest view that would lie inside the given bounds (if it's not already), controlling the animation using the options specific, if any.
panBy( <Point> point, <pan options> options? ) this Pans the map by a given number of pixels (animated).
invalidateSize( <Boolean> animate ) this Checks if the map container size changed and updates the map if so — call it after you've changed the map size dynamically, also animating pan by default.
invalidateSize( <zoom/pan options> options ) this Checks if the map container size changed and updates the map if so — call it after you've changed the map size dynamically, also animating pan by default. If options.pan is false, panning will not occur. If options.debounceMoveend is true, it will delay moveend event so that it doesn't happen often even if the method is called many times in a row.
setMaxBounds( <LatLngBounds> bounds this Restricts the map view to the given bounds (see map maxBounds option).
locate( <Locate options> options? ) this Tries to locate the user using the Geolocation API, firing a locationfound event with location data on success or a locationerror event on failure, and optionally sets the map view to the user's location with respect to detection accuracy (or to the world view if geolocation failed). See Locate options for more details.
stopLocate() this Stops watching location previously initiated by map.locate({watch: true}) and aborts resetting the map view if map.locate was called with {setView: true}.
remove() this Destroys the map and clears all related event listeners.
flyTo( <LatLng> latlng, <Number> zoom?, <zoom/pan options> options? ) this Sets the view of the map (geographical center and zoom) performing a smooth pan-zoom animation.
flyToBounds( <LatLngBounds> bounds, <fitBounds options> options? ) this Sets the view of the map with a smooth animation like flyTo, but takes a bounds parameter like fitBounds.

Methods for Getting Map State

Method Returns Description
getCenter() LatLng Returns the geographical center of the map view.
getZoom() Number Returns the current zoom of the map view.
getMinZoom() Number Returns the minimum zoom level of the map.
getMaxZoom() Number Returns the maximum zoom level of the map.
getBounds() LatLngBounds Returns the LatLngBounds of the current map view.
getBoundsZoom( <LatLngBounds> bounds, <Boolean> inside? ) Number Returns the maximum zoom level on which the given bounds fit to the map view in its entirety. If inside (optional) is set to true, the method instead returns the minimum zoom level on which the map view fits into the given bounds in its entirety.
getSize() Point Returns the current size of the map container.
getPixelBounds() Bounds Returns the bounds of the current map view in projected pixel coordinates (sometimes useful in layer and overlay implementations).
getPixelOrigin() Point Returns the projected pixel coordinates of the top left point of the map layer (useful in custom layer and overlay implementations).
getPixelWorldBounds( <Number> zoom? ) Bounds Returns the world's bounds in pixel coordinates for zoom level zoom. If zoom is omitted, the map's current zoom is used.

Methods for Layers and Controls

Method Returns Description
addLayer( <ILayer> layer this Adds the given layer to the map.
removeLayer( <ILayer> layer ) this Removes the given layer from the map.
hasLayer( <ILayer> layer ) Boolean Returns true if the given layer is currently added to the map.
eachLayer( <Function> fn, <Object> context? ) this Iterates over the layers of the map, optionally specifying context of the iterator function.
map.eachLayer(function (layer) {
	layer.bindPopup('Hello');
});
openPopup( <Popup> popup ) this Opens the specified popup while closing the previously opened (to make sure only one is opened at one time for usability).
openPopup( <String> html | <HTMLElement> el, <LatLng> latlng, <Popup options> options? ) this Creates a popup with the specified options and opens it in the given point on a map.
closePopup( <Popup> popup? ) this Closes the popup previously opened with openPopup (or the given one).
addControl( <IControl> control ) this Adds the given control to the map.
removeControl( <IControl> control ) this Removes the given control from the map.
getRenderer( <ILayer> layer) Renderer Returns the renderer for the given layer.

Conversion Methods

Method Returns Description
latLngToLayerPoint( <LatLng> latlng ) Point Returns the map layer point that corresponds to the given geographical coordinates (useful for placing overlays on the map).
layerPointToLatLng( <Point> point ) LatLng Returns the geographical coordinates of a given map layer point.
containerPointToLayerPoint( <Point> point ) Point Converts the point relative to the map container to a point relative to the map layer.
layerPointToContainerPoint( <Point> point ) Point Converts the point relative to the map layer to a point relative to the map container.
latLngToContainerPoint( <LatLng> latlng ) Point Returns the map container point that corresponds to the given geographical coordinates.
containerPointToLatLng( <Point> point ) LatLng Returns the geographical coordinates of a given map container point.
project( <LatLng> latlng, <Number> zoom? ) Point Projects the given geographical coordinates to absolute pixel coordinates for the given zoom level (current zoom level by default).
unproject( <Point> point, <Number> zoom? ) LatLng Projects the given absolute pixel coordinates to geographical coordinates for the given zoom level (current zoom level by default).
mouseEventToContainerPoint( <MouseEvent> event ) Point Returns the pixel coordinates of a mouse click (relative to the top left corner of the map) given its event object.
mouseEventToLayerPoint( <MouseEvent> event ) Point Returns the pixel coordinates of a mouse click relative to the map layer given its event object.
mouseEventToLatLng( <MouseEvent> event ) LatLng Returns the geographical coordinates of the point the mouse clicked on given the click's event object.
wrapLatLng( <LatLng> latlng ) LatLng Returns a LatLng where lat and lng has been wrapped according to the map's CRS's wrapLat and wrapLng properties, if they are outside the CRS's bounds.
distance( <LatLng> latlng1, <LatLng> latlng2 ) LatLng Returns the distance in meters between two geographic coordinates in the map's CRS.

Other Methods

Method Returns Description
getContainer() HTMLElement Returns the container element of the map.
createPane( <String> name, <HTMLElement> contianer? ) MapPane Creates a pane with the given name. Created panes will be given a generated class based on the name like .leaflet-pane-name"
getPane( <String> name ) MapPane Returns the HTML element representing the named map pane.
getPanes() MapPanes Returns an object with different map panes (to render overlays in).
whenReady( <Function> fn, <Object> context? ) this Runs the given callback when the map gets initialized with a place and zoom, or immediately if it happened already, optionally passing a function context.

Locate options

Option Type Default Description
watch Boolean false If true, starts continous watching of location changes (instead of detecting it once) using W3C watchPosition method. You can later stop watching using map.stopLocate() method.
setView Boolean false If true, automatically sets the map view to the user location with respect to detection accuracy, or to world view if geolocation failed.
maxZoom Number Infinity The maximum zoom for automatic view setting when using `setView` option.
timeout Number 10000 Number of milliseconds to wait for a response from geolocation before firing a locationerror event.
maximumAge Number 0 Maximum age of detected location. If less than this amount of milliseconds passed since last geolocation response, locate will return a cached location.
enableHighAccuracy Boolean false Enables high accuracy, see description in the W3C spec.

Zoom/pan options

Option Type Default Description
reset Boolean false If true, the map view will be completely reset (without any animations).
pan pan options - Sets the options for the panning (without the zoom change) if it occurs.
zoom zoom options - Sets the options for the zoom change if it occurs.
animate Boolean - An equivalent of passing animate to both zoom and pan options (see below).

Pan options

Option Type Default Description
animate Boolean - If true, panning will always be animated if possible. If false, it will not animate panning, either resetting the map view if panning more than a screen away, or just setting a new offset for the map pane (except for `panBy` which always does the latter).
duration Number 0.25 Duration of animated panning.
easeLinearity Number 0.25 The curvature factor of panning animation easing (third parameter of the Cubic Bezier curve). 1.0 means linear animation, the less the more bowed the curve.
noMoveStart Boolean false If true, panning won't fire movestart event on start (used internally for panning inertia).

Zoom options

Option Type Default Description
animate Boolean - If not specified, zoom animation will happen if the zoom origin is inside the current view. If true, the map will attempt animating zoom disregarding where zoom origin is. Setting false will make it always reset the view completely without animation.

fitBounds options

The same as zoom/pan options and additionally:

Option Type Default Description
paddingTopLeft Point [0, 0] Sets the amount of padding in the top left corner of a map container that shouldn't be accounted for when setting the view to fit bounds. Useful if you have some control overlays on the map like a sidebar and you don't want them to obscure objects you're zooming to.
paddingBottomRight Point [0, 0] The same for bottom right corner of the map.
padding Point [0, 0] Equivalent of setting both top left and bottom right padding to the same value.
maxZoom Number null The maximum possible zoom to use.

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 &copy; GeoNames");
Property Type Description
dragging IHandler Map dragging handler (by both mouse and touch).
touchZoom IHandler Touch zoom handler.
doubleClickZoom IHandler Double click zoom handler.
scrollWheelZoom IHandler Scroll wheel zoom handler.
boxZoom IHandler Box (shift-drag with mouse) zoom handler.
keyboard IHandler Keyboard navigation handler.
tap IHandler Mobile touch hacks (quick tap and touch hold) handler.
zoomControl Control.Zoom Zoom control.
attributionControl Control.Attribution Attribution control.

Map Panes

Panes are DOM elements used to control the ordering of layers on the map. You can access panes with map.getPane or map.getPanesmethods. New panes can be created with the map.createPane method.

Every map has the following panes that differ only in zIndex.

Pane Type Z Index Description
mapPane HTMLElement 'auto' Pane that contains all other map panes.
tilePane HTMLElement 2 Pane for tile layers.
overlayPane HTMLElement 4 Pane for overlays like polylines and polygons.
shadowPane HTMLElement 5 Pane for overlay shadows (e.g. marker shadows).
markerPane HTMLElement 6 Pane for marker icons.
popupPane HTMLElement 7 Pane for popups.

Marker

Used to put markers on the map. Extends Layer.

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

Creation

Factory Description
L.marker( <LatLng> latlng, <Marker options> options? ) Instantiates a Marker object given a geographical point and optionally an options object.

Options

Option Type Default Description
icon L.Icon * Icon class to use for rendering the marker. See Icon documentation for details on how to customize the marker icon. Set to new L.Icon.Default() by default.
interactive Boolean true If false, the marker will not emit mouse events and will act as a part of the underlying map.
draggable Boolean false Whether the marker is draggable with mouse/touch or not.
keyboard Boolean true Whether the marker can be tabbed to with a keyboard and clicked by pressing enter.
title String '' Text for the browser tooltip that appear on marker hover (no tooltip by default).
alt String '' Text for the alt attribute of the icon image (useful for accessibility).
zIndexOffset Number 0 By default, marker images zIndex is set automatically based on its latitude. Use this option if you want to put the marker on top of all others (or below), specifying a high value like 1000 (or high negative value, respectively).
opacity Number 1.0 The opacity of the marker.
riseOnHover Boolean false If true, the marker will get on top of others when you hover the mouse over it.
riseOffset Number 250 The z-index offset used for the riseOnHover feature.
pane String 'markerPane' Map pane where the markers icon will be added.
shadowPane String 'shadowPane' Map pane where the markers shadow will be added.

Events

You can subscribe to the following events using these methods.

Event Data Description
click MouseEvent Fired when the user clicks (or taps) the marker.
dblclick MouseEvent Fired when the user double-clicks (or double-taps) the marker.
mousedown MouseEvent Fired when the user pushes the mouse button on the marker.
mouseover MouseEvent Fired when the mouse enters the marker.
mouseout MouseEvent Fired when the mouse leaves the marker.
contextmenu MouseEvent Fired when the user right-clicks on the marker.
dragstart Event Fired when the user starts dragging the marker.
drag Event Fired repeatedly while the user drags the marker.
dragend DragEndEvent Fired when the user stops dragging the marker.
move Event Fired when the marker is moved via setLatLng. Old and new coordinates are included in event arguments as oldLatLng, latlng.
add Event Fired when the marker is added to the map.
remove Event Fired when the marker is removed from the map.
popupopen PopupEvent Fired when a popup bound to the marker is open.
popupclose PopupEvent Fired when a popup bound to the marker is closed.

Methods

In addition to shared layer methods like addTo() and remove() and popup methods like bindPopup() you can also use the following methods:

Method Returns Description
getLatLng() LatLng Returns the current geographical position of the marker.
setLatLng( <LatLng> latlng ) this Changes the marker position to the given point.
setIcon( <Icon> icon ) this Changes the marker icon.
setZIndexOffset( <Number> offset ) this Changes the zIndex offset of the marker.
setOpacity( <Number> opacity ) this Changes the opacity of the marker.
update() this Updates the marker position, useful if coordinates of its latLng object were changed directly.
toGeoJSON() Object Returns a GeoJSON representation of the marker (GeoJSON Point Feature).

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();
Property Type Description
dragging IHandler Marker dragging handler (by both mouse and touch).

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

Factory Description
L.popup( <Popup options> options?, <ILayer> source? ) Instantiates a Popup object given an optional options object that describes its appearance and location and an optional source object that is used to tag the popup with a reference to the ILayer to which it refers.
Option Type Default Description
maxWidth Number 300 Max width of the popup.
minWidth Number 50 Min width of the popup.
maxHeight Number null If set, creates a scrollable container of the given height inside a popup if its content exceeds it.
autoPan Boolean true Set it to false if you don't want the map to do panning animation to fit the opened popup.
keepInView Boolean false Set it to true if you want to prevent users from panning the popup off of the screen while it is open.
closeButton Boolean true Controls the presense of a close button in the popup.
offset Point Point(0, 6) The offset of the popup position. Useful to control the anchor of the popup when opening it on some overlays.
autoPanPaddingTopLeft Point null The margin between the popup and the top left corner of the map view after autopanning was performed.
autoPanPaddingBottomRight Point null The margin between the popup and the bottom right corner of the map view after autopanning was performed.
autoPanPadding Point Point(5, 5) Equivalent of setting both top left and bottom right autopan padding to the same value.
zoomAnimation Boolean true Whether to animate the popup on zoom. Disable it if you have problems with Flash content inside popups.
closeOnClick Boolean null Set it to false if you want to override the default behavior of the popup closing when user clicks the map (set globally by the Map closePopupOnClick option).
className String '' A custom class name to assign to the popup.

Events

Event Data Description
added PopupEvent Fired when the popup is added to the map.
removed PopupEvent Fired when the popup is removed from the map.

Methods

In addition to shared layer methods like addTo() and remove() you can also use the following methods:

Method Returns Description
openOn( <Map> map ) this Adds the popup to the map and closes the previous one. The same as map.openPopup(popup).
setLatLng( <LatLng> latlng ) this Sets the geographical point where the popup will open.
getLatLng() LatLng Returns the geographical point of popup.
setContent( <String|HTMLElement|Function> htmlContent ) this Sets the HTML content of the popup. If a function is passed the source layer will be passed to the function. The function should return a String or HTMLElement to be used in the popup.
getContent() <String|HTMLElement> Returns the content of the popup.
update() this Updates the popup content, layout and position. Useful for updating the popup after something inside changed, e.g. image loaded.

TileLayer

Used to load and display tile layers on the map. Extends Layer.

Usage example

L.tileLayer('http://{s}.tile.osm.org/{z}/{x}/{y}.png?{foo}', {foo: 'bar'}).addTo(map);

Creation

Factory Description
L.tileLayer( <String> urlTemplate, <TileLayer options> options? ) Instantiates a tile layer object given a URL template and optionally an options object.

URL template

A string of the following form:

'http://{s}.somedomain.com/blabla/{z}/{x}/{y}{r}.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. {r} can be used to add @2x to the URL to load retina tiles.

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

Option Type Default Description
minZoom Number 0 Minimum zoom number.
maxZoom Number 18 Maximum zoom number.
maxNativeZoom Number null Maximum zoom number the tiles source has available. If it is specified, the tiles on all zoom levels higher than maxNativeZoom will be loaded from maxZoom level and auto-scaled.
tileSize Number 256 Tile size (width and height in pixels, assuming tiles are square).
subdomains String or String[] 'abc' Subdomains of the tile service. Can be passed in the form of one string (where each letter is a subdomain name) or an array of strings.
errorTileUrl String '' URL to the tile image to show in place of the tile that failed to load.
attribution String '' e.g. "© Mapbox" — the string used by the attribution control, describes the layer data.
tms Boolean false If true, inverses Y axis numbering for tiles (turn this on for TMS services).
continuousWorld Boolean false If set to true, the tile coordinates won't be wrapped by world width (-180 to 180 longitude) or clamped to lie within world height (-90 to 90). Use this if you use Leaflet for maps that don't reflect the real world (e.g. game, indoor or photo maps).
noWrap Boolean false If set to true, the tiles just won't load outside the world width (-180 to 180 longitude) instead of repeating.
zoomOffset Number 0 The zoom number used in tile URLs will be offset with this value.
zoomReverse Boolean false If set to true, the zoom number used in tile URLs will be reversed (maxZoom - zoom instead of zoom)
opacity Number 1.0 The opacity of the tile layer.
zIndex Number null The explicit zIndex of the tile layer. Not set by default.
updateInterval Number 200 Tiles will not update more then once every updateInterval.
unloadInvisibleTiles Boolean depends If true, all the tiles that are not visible after panning are removed (for better performance). true by default on mobile WebKit, otherwise false.
updateWhenIdle Boolean depends If false, new tiles are loaded during panning, otherwise only after it (for better performance). true by default on mobile WebKit, otherwise false.
detectRetina Boolean false If true and user is on a retina display, it will request four tiles of half the specified size and a bigger zoom level in place of one to utilize the high resolution.
reuseTiles Boolean false If true, all the tiles that are not visible after panning are placed in a reuse queue from which they will be fetched when new tiles become visible (as opposed to dynamically creating new ones). This will in theory keep memory usage low and eliminate the need for reserving new memory whenever a new tile is needed.
bounds LatLngBounds null When this option is set, the TileLayer only loads tiles that are in the given geographical bounds.
crossOrigin Boolean false If true, all tiles will have their crossOrigin attribute set to ''. This is needed if you want to access tile pixel data.

Events

You can subscribe to the following events using these methods.

Event Data Description
loading Event Fired when the tile layer starts loading tiles.
load Event Fired when the tile layer loaded all visible tiles.
tileloadstart TileEvent Fired when a tile is requested and starts loading.
tileload TileEvent Fired when a tile loads.
tileunload TileEvent Fired when a tile is removed (e.g. when you have unloadInvisibleTiles on).
tileerror TileEvent Fired when there is an error loading a tile.

Methods

Method Returns Description
addTo( <Map> map ) this Adds the layer to the map.
bringToFront() this Brings the tile layer to the top of all tile layers.
bringToBack() this Brings the tile layer to the bottom of all tile layers.
setOpacity( <Number> opacity ) this Changes the opacity of the tile layer.
setZIndex( <Number> zIndex ) this Sets the zIndex of the tile layer.
redraw() this Causes the layer to clear all the tiles and request them again.
setUrl( <String> urlTemplate ) this Updates the layer's URL template and redraws it.
getContainer() HTMLElement Returns the HTML element that contains the tiles for this layer.

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

Factory Description
L.tileLayer.wms( <String> baseUrl, <TileLayer.WMS options> options ) Instantiates a WMS tile layer object given a base URL of the WMS service and a WMS parameters/options object.

Options

Includes all TileLayer options and additionally:

Option Type Default Description
layers String '' (required) Comma-separated list of WMS layers to show.
styles String '' Comma-separated list of WMS styles.
format String 'image/jpeg' WMS image format (use 'image/png' for layers with transparency).
transparent Boolean false If true, the WMS service will return images with transparency.
version String '1.1.1' Version of the WMS service to use.
crs CRS null Coordinate Reference System to use for the WMS requests, defaults to map CRS. Don't change this if you're not sure what it means.
uppercase Boolean false If true, WMS request parameter keys will be uppercase.

Methods

Method Returns Description
setParams( <WMS parameters> params, <Boolean> noRedraw? ) this Merges an object with the new parameters and re-requests tiles on the current screen (unless noRedraw was set to true).

ImageOverlay

Used to load and display a single image over specific bounds of the map. Extends Layer.

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

Factory Description
L.ImageOverlay( <String> imageUrl, <LatLngBounds> bounds, <ImageOverlay options> options? ) Instantiates an image overlay object given the URL of the image and the geographical bounds it is tied to.

Options

Option Type Default Description
opacity Number 1.0 The opacity of the image overlay.
attribution String '' The attribution text of the image overlay.

Methods

Method Returns Description
addTo( <Map> map ) this Adds the overlay to the map.
setOpacity( <Number> opacity ) this Sets the opacity of the overlay.
setUrl( <String> imageUrl ) this Changes the URL of the image.
bringToFront() this Brings the layer to the top of all overlays.
bringToBack() this Brings the layer to the bottom of all overlays.

Path

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

Options

Option Type Default Description
stroke Boolean true Whether to draw stroke along the path. Set it to false to disable borders on polygons or circles.
color String '#3388ff' Stroke color.
weight Number 3 Stroke width in pixels.
opacity Number 1 Stroke opacity.
fill Boolean depends Whether to fill the path with color. Set it to false to disable filling on polygons or circles.
fillColor String same as color Fill color.
fillOpacity Number 0.2 Fill opacity.
fillRule String 'evenodd' A string that defines how the inside of a shape is determined.
dashArray String null A string that defines the stroke dash pattern. Doesn't work on canvas-powered layers (e.g. Android 2).
lineCap String 'round' A string that defines shape to be used at the end of the stroke.
lineJoin String 'round' A string that defines shape to be used at the corners of the stroke.
interactive Boolean true If false, the vector will not emit mouse events and will act as a part of the underlying map.
renderer Renderer depends L.SVG or L.Canvas by default depending on browser support.
pointerEvents String null Sets the pointer-events attribute on the path if SVG renderer is used.
className String '' Custom class name set on an element.

Events

You can subscribe to the following events using these methods.

Event Data Description
click MouseEvent Fired when the user clicks (or taps) the object.
dblclick MouseEvent Fired when the user double-clicks (or double-taps) the object.
mousedown MouseEvent Fired when the user pushes the mouse button on the object.
mouseover MouseEvent Fired when the mouse enters the object.
mouseout MouseEvent Fired when the mouse leaves the object.
contextmenu MouseEvent Fired when the user pushes the right mouse button on the object, prevents default browser context menu from showing if there are listeners on this event.
add Event Fired when the path is added to the map.
remove Event Fired when the path is removed from the map.
popupopen PopupEvent Fired when a popup bound to the path is open.
popupclose PopupEvent Fired when a popup bound to the path is closed.

Methods

In addition to shared layer methods like addTo() and remove() and popup methods like bindPopup() you can also use the following methods:

Method Returns Description
openPopup( <LatLng> latlng? ) this Opens the popup previously bound by the bindPopup method in the given point, or in one of the path's points if not specified.
setStyle( <Path options> object ) this Changes the appearance of a Path based on the options in the Path options object.
getBounds() LatLngBounds Returns the LatLngBounds of the path.
bringToFront() this Brings the layer to the top of all path layers.
bringToBack() this Brings the layer to the bottom of all path layers.
redraw() this Redraws the layer. Sometimes useful after you changed the coordinates that the path uses.

Static properties

Constant Type Value Description
SVG Boolean depends True if SVG is used for vector rendering (true for most modern browsers).
VML Boolean depends True if VML is used for vector rendering (IE 6-8).
CANVAS Boolean depends True if Canvas is used for vector rendering (Android 2). You can also force this by setting global variable L_PREFER_CANVAS to true before the Leaflet include on your page — sometimes it can increase performance dramatically when rendering thousands of circle markers, but currently suffers from a bug that causes removing such layers to be extremely slow.
CLIP_PADDING Number 0.5 for SVG
0.02 for VML
How much to extend the clip area around the map view (relative to its size, e.g. 0.5 is half the screen in each direction). Smaller values mean that you will see clipped ends of paths while you're dragging the map, and bigger values decrease drawing performance.

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 array of LatLng points
var latlngs = [
  [-122.68, 45.51],
  [-122.43, 37.77],
  [-118.2, 34.04]
];

var polyline = L.polyline(latlngs, {color: 'red'}).addTo(map);

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

You can also pass a multi-dimensional array to represent a MultiPolyline shape:

// create a red polyline from an array of arrays of LatLng points
var latlngs = [
  [[-122.68, 45.51],
   [-122.43, 37.77],
   [-118.2, 34.04]],
  [[-73.91, 40.78],
   [-87.62, 41.83],
   [-96.72, 32.76]]
];

Creation

Factory Description
L.polyline( <LatLng[]> latlngs, <Polyline options> options? ) Instantiates a polyline object given an array of geographical points and optionally an options object. You can create a Polyline object with multiple separate lines (MultiPolyline) by passing an array of arrays of geographic points.

Options

You can use Path options and additionally the following options:

Option Type Default Description
smoothFactor Number 1.0 How much to simplify the polyline on each zoom level. More means better performance and smoother look, and less means more accurate representation.
noClip Boolean false Disabled polyline clipping.

Methods

In addition to Path methods like redraw() and bringToFront(), shared layer methods like addTo() and remove() and popup methods like bindPopup() you can also use the following methods:

Method Returns Description
addLatLng( <LatLng> latlng, <LatLng[]> latlngs ) this Adds a given point to the polyline. By default, adds to the first ring of the polyline in case of a multi-polyline, but can be overridden by passing a specific ring as a LatLng array (that you can earlier access with getLatLngs).
setLatLngs( <LatLng[]> latlngs ) this Replaces all the points in the polyline with the given array of geographical points.
getLatLngs() LatLng[] Returns an array of the points in the path, or nested arrays of points in case of multi-polyline.
isEmpty() Boolean Returns true if the Polyline has no LatLng.
getBounds() LatLngBounds Returns the LatLngBounds of the polyline.
getCenter() LatLng Returns the center (centroid) of the polyline.
toGeoJSON() Object Returns a GeoJSON representation of the polyline (GeoJSON LineString Feature).

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.

Usage example

// create a red polygon from an array of LatLng points
var latlngs = [[-111.03, 41],[-111.04, 45],[-104.05, 45],[-104.05, 41]];

var polygon = L.polygon(latlngs, {color: 'red'}).addTo(map);

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

You can also pass an array of arrays of latlngs, with the first array representing the outer shape and the other arrays representing holes in the outer shape:


var latlngs = [
  [[-111.03, 41],[-111.04, 45],[-104.05, 45],[-104.05, 41]], // outer ring
  [[-108.58,37.29],[-108.58,40.71],[-102.50,40.71],[-102.50,37.29]] // hole
];

Additionally, you can pass a multi-dimensional array to represent a MultiPolygon shape.


var latlngs = [
  [ // first polygon
    [[-111.03, 41],[-111.04, 45],[-104.05, 45],[-104.05, 41]], // outer ring
    [[-108.58,37.29],[-108.58,40.71],[-102.50,40.71],[-102.50,37.29]] // hole
  ],
  [ // second polygon
    [[-109.05, 37],[-109.03, 41],[-102.05, 41],[-102.04, 37],[-109.05, 38]]
  ]
];

Creation

Factory Description
L.polygon( <LatLng[]> latlngs, <Polyline options> options? ) Instantiates a polygon object given an array of geographical points and optionally an options object (the same as for Polyline). You can also create a polygon with holes by passing an array of arrays of latlngs, with the first latlngs array representing the exterior ring while the remaining represent the holes inside. You can create a a Polygon with multiple separate shapes (MultiPolygon) by passing an array of Polygon coordinates.

Methods

In addition to Path methods like redraw() and bringToFront(), Polyline mehtods like setLatLngs() and getLatLngs(), shared layer methods like addTo() and remove() and popup methods like bindPopup() you can also use the following methods:

Method Returns Description
toGeoJSON() Object Returns a GeoJSON representation of the polygon (GeoJSON Polygon Feature).

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

Factory Description
L.rectangle( <LatLngBounds> bounds, <Path options> options? ) Instantiates a rectangle object with the given geographical bounds and optionally an options object.

Methods

In addition to Path methods like redraw() and bringToFront(), shared layer methods like addTo() and remove() and popup methods like bindPopup() you can also use the following methods:

Method Returns Description
setBounds( <LatLngBounds> bounds ) this Redraws the rectangle with the passed bounds.

Circle

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

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

Creation

Factory Description
L.circle( <LatLng> latlng, <Number> radius, <Path options> options? ) Instantiates a circle object given a geographical point, a radius in meters and optionally an options object.

Methods

In addition to Path methods like redraw() and bringToFront(), shared layer methods like addTo() and remove() and popup methods like bindPopup() you can also use the following methods:

Method Returns Description
getLatLng() LatLng Returns the current geographical position of the circle.
getRadius() Number Returns the current radius of a circle. Units are in meters.
setLatLng( <LatLng> latlng ) this Sets the position of a circle to a new location.
setRadius( <Number> radius ) this Sets the radius of a circle. Units are in meters.
toGeoJSON() Object Returns a GeoJSON representation of the circle (GeoJSON Point Feature).

CircleMarker

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

Creation

Factory Description
L.circleMarker( <LatLng> latlng, <Path options> options? ) Instantiates a circle marker given a geographical point and optionally an options object. The default radius is 10 and can be altered by passing a "radius" member in the path options object.

Methods

In addition to Path methods like redraw() and bringToFront(), shared layer methods like addTo() and remove() and popup methods like bindPopup() you can also use the following methods:

Method Returns Description
setLatLng( <LatLng> latlng ) this Sets the position of a circle marker to a new location.
setRadius( <Number> radius ) this Sets the radius of a circle marker. Units are in pixels.
toGeoJSON() Object Returns a GeoJSON representation of the circle marker (GeoJSON Point Feature).

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. Extends Layer.

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

Creation

Factory Description
L.LayerGroup( <ILayer[]> layers? ) Create a layer group, optionally given an initial set of layers.

Methods

Method Returns Description
addTo( <Map> map ) this Adds the group of layers to the map.
addLayer( <ILayer> layer ) this Adds a given layer to the group.
removeLayer( <ILayer> layer ) this Removes a given layer from the group.
removeLayer( <String> id ) this Removes a given layer of the given id from the group.
hasLayer( <ILayer> layer ) Boolean Returns true if the given layer is currently added to the group.
getLayer( <String> id ) ILayer Returns the layer with the given id.
getLayers() Array Returns an array of all the layers added to the group.
clearLayers() this Removes all the layers from the group.
eachLayer( <Function> fn, <Object> context? ) this Iterates over the layers of the group, optionally specifying context of the iterator function.
group.eachLayer(function (layer) {
	layer.bindPopup('Hello');
});
toGeoJSON() Object Returns a GeoJSON representation of the layer group (GeoJSON FeatureCollection).

FeatureGroup

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

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

Creation

Factory Description
L.featureGroup( <ILayer[]> layers? ) Create a layer group, optionally given an initial set of layers.

Methods

In addition to shared layer methods like addTo() and remove() and popup methods like bindPopup() you can also use the following methods:

Method Returns Description
getBounds() LatLngBounds Returns the LatLngBounds of the Feature Group (created from bounds and coordinates of its children).
setStyle( <Path options> style ) this Sets the given path options to each layer of the group that has a setStyle method.
bringToFront() this Brings the layer group to the top of all other layers.
bringToBack() this Brings the layer group to the bottom of all other layers.

Events

You can subscribe to the following events using these methods.

Event Data Description
click MouseEvent Fired when the user clicks (or taps) the group.
dblclick MouseEvent Fired when the user double-clicks (or double-taps) the group.
mouseover MouseEvent Fired when the mouse enters the group.
mouseout MouseEvent Fired when the mouse leaves the group.
mousemove MouseEvent Fired while the mouse moves over the layers of the group.
contextmenu MouseEvent Fired when the user right-clicks on one of the layers.
layeradd LayerEvent Fired when a layer is added to the group.
layerremove LayerEvent Fired when a layer is removed from the map.

GeoJson

Represents a GeoJSON object or an array of GeoJSON objects. 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};
	}
}).bindPopup(function (layer) {
	return layer.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

Factory Description
L.geoJson( <Object> geojson?, <GeoJSON options> options? ) Creates a GeoJSON layer. Optionally accepts an object in GeoJSON format to display on the map (you can alternatively add it later with addData method) and an options object.

Options

Option Description
pointToLayer( <GeoJSON> featureData, <LatLng> latlng ) Function that will be used for creating layers for GeoJSON points (if not specified, simple markers will be created).
style( <GeoJSON> featureData ) Function that will be used to get style options for vector layers created for GeoJSON features.
onEachFeature( <GeoJSON> featureData, <ILayer> layer ) Function that will be called on each created feature layer. Useful for attaching events and popups to features.
filter( <GeoJSON> featureData, <ILayer> layer ) Function that will be used to decide whether to show a feature or not.
coordsToLatLng( <Array> coords ) Function that will be used for converting GeoJSON coordinates to LatLng points (if not specified, coords will be assumed to be WGS84 — standard [longitude, latitude] values in degrees).

Additionally accepts all Path options for polylines and polygons.

Methods

In addition to shared layer methods like addTo() and remove() and popup methods like bindPopup() you can also use the following methods:

Method Returns Description
addData( <GeoJSON> data ) this Adds a GeoJSON object to the layer.
setStyle( <Function> style ) this Changes styles of GeoJSON vector layers with the given style function.
resetStyle( <Path> layer ) this Resets the given vector layer's style to the original GeoJSON style, useful for resetting style after hover events.

Static methods

Method Returns Description
geometryToLayer( <GeoJSON> featureData, <Function> pointToLayer? ) ILayer Creates a layer from a given GeoJSON feature.
coordsToLatLng( <Array> coords, <Boolean> reverse? ) LatLng Creates a LatLng object from an array of 2 numbers (latitude, longitude) used in GeoJSON for points. If reverse is set to true, the numbers will be interpreted as (longitude, latitude).
coordsToLatLngs( <Array> coords, <Number> levelsDeep?, <Boolean> reverse? ) Array Creates a multidimensional array of LatLng objects from a GeoJSON coordinates array. levelsDeep specifies the nesting level (0 is for an array of points, 1 for an array of arrays of points, etc., 0 by default). If reverse is set to true, the numbers will be interpreted as (longitude, latitude).

GridLayer

Generic class for handling a tiled grid of HTML elements. This is the base class for all tile layers and replaces TileLayer.Canvas.

GridLayer can be extended to create a tiled grid of HTML Elements like <canvas>, <img> or <div>.GridLayer will handle creating and animating these DOM elements for you.

Synchronous usage example

To create a custom layer, extend GridLayer and impliment the createTile() method, which will be passed a Point object with the x, y, and z (zoom level) coordinates to draw your tile.

var CanvasLayer = L.GridLayer.extend({
	createTile: function(coords){
		// create a <canvas> element for drawing
		var tile = L.DomUtil.create('canvas', 'leaflet-tile');

		// setup tile width and height according to the options
		var size = this.getTileSize();
		tile.width = size.x;
		tile.height = size.y;

		// get a canvas context and draw something on it using coords.x, coords.y and coords.z
		var ctx = canvas.getContext('2d');

		// return the tile so it can be rendered on screen
		return tile;
	}
});

Asyncronous usage example

Tile creation can also be asyncronous, this is useful when using a third-party drawing library. Once the tile is finsihed drawing it can be passed to the done() callback.

var CanvasLayer = L.GridLayer.extend({
	createTile: function(coords, done){
		var error;

		// create a <canvas> element for drawing
		var tile = L.DomUtil.create('canvas', 'leaflet-tile');

		// setup tile width and height according to the options
		var size = this.getTileSize();
		tile.width = size.x;
		tile.height = size.y;

		// draw something and pass the tile to the done() callback
		done(error, tile);
	}
});

Constructor

Factory Description
L.gridLayer(<GridLayer options> options?) Creates a new instance of GridLayer with the supplied options.

Options

Option Type Default value Description
maxZoom Number 'tilePane' The map pane the layer will be added to.
tileSize Number or Point 256 Width and height of tiles in the grid. Use a number if width and height are equal, or L.point(width, height) otherwise.
opacity Number 1 Opacity of the tiles. Can be used in the createTile() function.
unloadInvisibleTiles Boolean depends If true, all the tiles that are not visible after panning are removed (for better performance). true by default on mobile WebKit, otherwise false.
updateWhenIdle Boolean depends If false, new tiles are loaded during panning, otherwise only after it (for better performance). true by default on mobile WebKit, otherwise false.
updateInterval Number 200 Tiles will not update more then once every updateInterval.
zIndex Number null The explicit zIndex of the tile layer. Not set by default.
bounds LatLngBounds null If set tiles will only be loaded inside inside the set LatLngBounds.
bounds LatLngBounds null If set tiles will only be loaded inside inside the set LatLngBounds.
minZoom Number 0 The minimum zoom level that tiles will be loaded at. By default the entire map.

Methods

bringToFront() this Brings the tile layer to the top of all tile layers.
bringToBack() this Brings the tile layer to the bottom of all tile layers.
setOpacity( <Number> opacity ) this Changes the opacity of the tile layer.
setZIndex( <Number> zIndex ) this Sets the zIndex of the tile layer.
redraw() this Causes the layer to clear all the tiles and request them again.
getContainer() HTMLElement Returns the HTML element that contains the tiles for this layer.
getTileSize() Point Normalizes the tileSize option into a point. Used by the createTile() method.

Events

Event Data Description
loading Event Fired when the tile layer starts loading tiles.
load Event Fired when the tile layer loaded all visible tiles.
tileloadstart TileEvent Fired when a tile is requested and starts loading.
tileload TileEvent Fired when a tile loads.
tileunload TileEvent Fired when a tile is removed (e.g. when you have unloadInvisibleTiles on).
tileerror TileEvent Fired when there is an error loading a tile.

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

Factory Description
L.latLng( <Number> latitude, <Number> longitude, <Number> altitude? ) Creates an object representing a geographical point with the given latitude and longitude (and optionally altitude).

Properties

Property Type Description
lat Number Latitude in degrees.
lng Number Longitude in degrees.

Methods

Method Returns Description
distanceTo( <LatLng> otherLatlng ) Number Returns the distance (in meters) to the given LatLng calculated using the Haversine formula. See description on wikipedia
equals( <LatLng> otherLatlng, <Number> maxMargin? ) Boolean Returns true if the given LatLng point is at the same position (within a small margin of error). The margin of error can be overriden by setting maxMargin to a small number.
toString() String Returns a string representation of the point (for debugging purposes).
wrap( <Number> left, <Number> right ) LatLng Returns a new LatLng object with the longitude wrapped around left and right boundaries (-180 to 180 by default).

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

Factory Description
L.latLngBounds( <LatLng> southWest, <LatLng> northEast ) Creates a latLngBounds object by defining south-west and north-east corners of the rectangle.
L.latLngBounds( <LatLng[]> latlngs ) Creates a LatLngBounds object defined by the geographical points it contains. Very useful for zooming the map to fit a particular set of locations with fitBounds.

Methods

Method Returns Description
extend( <LatLng|LatLngBounds> latlng ) this Extends the bounds to contain the given point or bounds.
getSouthWest() LatLng Returns the south-west point of the bounds.
getNorthEast() LatLng Returns the north-east point of the bounds.
getNorthWest() LatLng Returns the north-west point of the bounds.
getSouthEast() LatLng Returns the south-east point of the bounds.
getWest() Number Returns the west longitude of the bounds.
getSouth() Number Returns the south latitude of the bounds.
getEast() Number Returns the east longitude of the bounds.
getNorth() Number Returns the north latitude of the bounds.
getCenter() LatLng Returns the center point of the bounds.
contains( <LatLngBounds> otherBounds ) Boolean Returns true if the rectangle contains the given one.
contains( <LatLng> latlng ) Boolean Returns true if the rectangle contains the given point.
intersects( <LatLngBounds> otherBounds ) Boolean Returns true if the rectangle intersects the given bounds. Two bounds intersect if they have at least one point in common.
overlaps( <LatLngBounds> otherBounds ) Boolean Returns true if the rectangle overlaps the given bounds. Two bounds overlap if their intersection is an area.
equals( <LatLngBounds> otherBounds ) Boolean Returns true if the rectangle is equivalent (within a small margin of error) to the given bounds.
toBBoxString() String Returns a string with bounding box coordinates in a 'southwest_lng,southwest_lat,northeast_lng,northeast_lat' format. Useful for sending requests to web services that return geo data.
pad( <Number> bufferRatio ) LatLngBounds Returns bigger bounds created by extending the current bounds by a given percentage in each direction.
isValid() Boolean Returns true if the bounds are properly initialized.

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

Factory Description
L.point( <Number> x, <Number> y, <Boolean> round? ) Creates a Point object with the given x and y coordinates. If optional round is set to true, rounds the x and y values.

Properties

Property Type Description
x Number The x coordinate.
y Number The y coordinate.

Methods

Method Returns Description
add( <Point> otherPoint ) Point Returns the result of addition of the current and the given points.
subtract( <Point> otherPoint ) Point Returns the result of subtraction of the given point from the current.
multiplyBy( <Number> number ) Point Returns the result of multiplication of the current point by the given number.
divideBy( <Number> number, <Boolean> round? ) Point Returns the result of division of the current point by the given number. If optional round is set to true, returns a rounded result.
scaleBy( <Point> scale ) Point Multiply each coordinate of the current point by each coordinate of scale. In linear algebra terms, multiply the point by the scaling matrix defined by scale.
unscaleBy( <Point> otherPoint ) Point Inverse of multiplyCoordinates. Divide each coordinate of the current point by each coordinate of scale.
distanceTo( <Point> otherPoint ) Number Returns the distance between the current and the given points.
clone() Point Returns a copy of the current point.
round() Point Returns a copy of the current point with rounded coordinates.
floor() Point Returns a copy of the current point with floored coordinates (rounded down).
ceil() Point Returns a copy of the current point with ceiled coordinates (rounded up).
equals( <Point> otherPoint ) Boolean Returns true if the given point has the same coordinates.
contains( <Point> otherPoint ) Boolean Returns true if the both coordinates of the given point are less than the corresponding current point coordinates (in absolute values).
toString() String Returns a string representation of the point for debugging purposes.

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

Factory Description
L.bounds( <Point> topLeft, <Point> bottomRight ) Creates a Bounds object from two coordinates (usually top-left and bottom-right corners).
L.bounds( <Point[]> points ) Creates a Bounds object defined by the points it contains.

Properties

Property Type Description
min Point The top left corner of the rectangle.
max Point The bottom right corner of the rectangle.

Methods

Method Returns Description
extend( <Point> point ) - Extends the bounds to contain the given point.
getCenter() Point Returns the center point of the bounds.
contains( <Bounds> otherBounds ) Boolean Returns true if the rectangle contains the given one.
contains( <Point> point ) Boolean Returns true if the rectangle contains the given point.
intersects( <Bounds> otherBounds ) Boolean Returns true if the rectangle intersects the given bounds. Two bounds intersect if they have at least one point in common.
overlaps( <Bounds> otherBounds ) Boolean Returns true if the rectangle overlaps the given bounds. Two bounds overlap if their intersection is an area.
isValid() Boolean Returns true if the bounds are properly initialized.
getSize() Point Returns the size of the given bounds.

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

Factory Description
L.icon( <Icon options> options ) Creates an icon instance with the given options.

Options

Option Type Description
iconUrl String (required) The URL to the icon image (absolute or relative to your script path).
iconRetinaUrl String The URL to a retina sized version of the icon image (absolute or relative to your script path). Used for Retina screen devices.
iconSize Point Size of the icon image in pixels.
iconAnchor Point The coordinates of the "tip" of the icon (relative to its top left corner). The icon will be aligned so that this point is at the marker's geographical location. Centered by default if size is specified, also can be set in CSS with negative margins.
shadowUrl String The URL to the icon shadow image. If not specified, no shadow image will be created.
shadowRetinaUrl String The URL to the retina sized version of the icon shadow image. If not specified, no shadow image will be created. Used for Retina screen devices.
shadowSize Point Size of the shadow image in pixels.
shadowAnchor Point The coordinates of the "tip" of the shadow (relative to its top left corner) (the same as iconAnchor if not specified).
popupAnchor Point The coordinates of the point from which popups will "open", relative to the icon anchor.
className String A custom class name to assign to both icon and shadow images. Empty by default.

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

Factory Description
L.divIcon( <DivIcon options> options ) Creates a div icon instance with the given options.

Options

Option Type Description
iconSize Point Size of the icon in pixels. Can be also set through CSS.
iconAnchor Point The coordinates of the "tip" of the icon (relative to its top left corner). The icon will be aligned so that this point is at the marker's geographical location. Centered by default if size is specified, also can be set in CSS with negative margins.
popupAnchor Point The coordinates of the point from which popups will "open", relative to the icon anchor.
className String A custom class name to assign to the icon. 'leaflet-div-icon' by default.
html String A custom HTML code to put inside the div element, empty by default.

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

Factory Description
L.control.zoom( <Control.Zoom options> options? ) Creates a zoom control.

Options

Option Type Default Description
position String 'topleft' The position of the control (one of the map corners). See control positions.
zoomInText String '+' The text set on the zoom in button.
zoomOutText String '-' The text set on the zoom out button.
zoomInTitle String 'Zoom in' The title set on the zoom in button.
zoomOutTitle String 'Zoom out' The title set on the zoom out button.

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

Factory Description
L.control.attribution( <Control.Attribution options> options? ) Creates an attribution control.

Options

Option Type Default Description
position String 'bottomright' The position of the control (one of the map corners). See control positions.
prefix String 'Leaflet' The HTML text shown before the attributions. Pass false to disable.

Methods

Method Returns Description
setPrefix( <String> prefix ) this Sets the text before the attributions.
addAttribution( <String> text ) this Adds an attribution text (e.g. 'Vector data &copy; Mapbox').
removeAttribution( <String> text ) this Removes an attribution text.

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 = {
	"Mapbox": mapbox,
	"OpenStreetMap": osm
};

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

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

Creation

Factory Description
L.control.layers( <Layer Config> baseLayers?, <Layer Config> overlays?, <Control.Layers options> options? ) Creates an attribution control with the given layers. Base layers will be switched with radio buttons, while overlays will be switched with checkboxes. Note that all base layers should be passed in the base layers object, but only one should be added to the map during map instantiation.

Methods

Method Returns Description
addBaseLayer( <ILayer> layer, <String> name ) this Adds a base layer (radio button entry) with the given name to the control.
addOverlay( <ILayer> layer, <String> name ) this Adds an overlay (checkbox entry) with the given name to the control.
removeLayer( <ILayer> layer ) this Remove the given layer from the control.

Options

Option Type Default Description
position String 'topright' The position of the control (one of the map corners). See control positions.
collapsed Boolean true If true, the control will be collapsed into an icon and expanded on mouse hover or touch.
autoZIndex Boolean true If true, the control will assign zIndexes in increasing order to all of its layers so that the order is preserved when switching them on/off.

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.

Event Data Description
baselayerchange LayersControlEvent Fired when the base layer is changed through the control.
overlayadd LayersControlEvent Fired when an overlay is selected through the control.
overlayremove LayersControlEvent Fired when an overlay is deselected through the control.

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

Factory Description
L.control.scale( <Control.Scale options> options? ) Creates an scale control with the given options.

Options

Option Type Default Description
position String 'bottomleft' The position of the control (one of the map corners). See control positions.
maxWidth Number 100 Maximum width of the control in pixels. The width is set dynamically to show round values (e.g. 100, 200, 500).
metric Boolean true Whether to show the metric scale line (m/km).
imperial Boolean true Whether to show the imperial scale line (mi/ft).
updateWhenIdle Boolean false If true, the control is updated on moveend, otherwise it's always up-to-date (updated on move).

Events methods

A set of methods shared between event-powered classes (like Map and Marker). 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 to fire 'click' 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

Method Returns Description
on( <String> type, <Function> fn, <Object> context? ) this Adds a listener function (fn) to a particular event type of the object. You can optionally specify the context of the listener (object the this keyword will point to). You can also pass several space-separated types (e.g. 'click dblclick').
once( <String> type, <Function> fn, <Object> context? ) this The same as above except the listener will only get fired once and then removed.
on( <Object> eventMap, <Object> context? ) this Adds a set of type/listener pairs, e.g. {click: onClick, mousemove: onMouseMove}
off( <String> type, <Function> fn?, <Object> context? ) this Removes a previously added listener function. If no function is specified, it will remove all the listeners of that particular event from the object. Note that if you passed a custom context to on, you must pass the same context to off in order to remove the listener.
off( <Object> eventMap, <Object> context? ) this Removes a set of type/listener pairs.
off() this Removes all listeners to all events on the object.
listens( <String> type ) Boolean Returns true if a particular event type has any listeners attached to it.
fire( <String> type, <Object> data? ) this Fires an event of the specified type. You can optionally provide an data object — the first argument of the listener function will contain its properties.
addEventListener( … ) this Alias to on.
addOneTimeEventListener( … ) this Alias to once.
removeEventListener( … ) this Alias to off.
clearAllEventListeners() this Alias to off().
hasEventListeners( … ) this Alias to listens.
fireEvent( … ) this Alias to fire.

Layer methods

A set of methods inherited from the Layer base class that all Leaflet layers use.
var layer = L.Marker(latlng).addTo(map);
layer.addTo(map);
layer.remove();

Methods

Method Returns Description
addTo(<Map> map) this Adds the layer to the given map.
removeFrom(<Map> map) this Removes the layer to the given map.
remove() this Removes the layer from the map it is currently active on.
getPane(<String> name?) HTMLElement Returns the HTMLElement representing the named pane on the map. Or if name is omitted the pane for this layer.

Popup methods

A set of methods inherited from the Layer base class that all Leaflet layers use. These methods provide convieniant ways of binding popups to any layer.
var layer = L.Polgon(latlngs).bindPopup('Hi There!').addTo(map);
layer.openPopup();
layer.closePopup();
Popups will also be automatically opened when the layer is clicked on and closed when the layer is removed from the map or another popup is opened.

Methods

featureGroup.bindPopup(function(layer){
	return "a unique template for this layer.";
});
Method Returns Description
bindPopup(<String|HTMLElement|Function|Popup> content, <PopupOptions> options?) this Binds the passed content to the layer and sets up the neccessary event listeners. If a Function is passed the function will recive a layer as the first argument and should return a String or HTMLElement.
unbindPopup() this Removes the popup previously bound with bindPopup.
openPopup(LatLng latlng?) this Opens the bound popup at the specificed latlng or at the default popup anchor if no latlng is passed.
closePopup() this Closes the popup if it is open.
togglePopup() this Opens or closes the popup depending on its current state.
setPopupContent(<String|HTMLElement|Popup> content, <PopupOptions> options?) this Sets the content of the popup.
getPopup() Popup Returns the popup bound to this layer.

Browser

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

if (L.Browser.ie6) {
	alert('Upgrade your browser, dude!');
}
property type description
ie Boolean true for all Internet Explorer versions.
ie6 Boolean true for Internet Explorer 6.
ie7 Boolean true for Internet Explorer 7.
webkit Boolean true for webkit-based browsers like Chrome and Safari (including mobile versions).
webkit3d Boolean true for webkit-based browsers that support CSS 3D transformations.
android Boolean true for Android mobile browser.
android23 Boolean true for old Android stock browsers (2 and 3).
mobile Boolean true for modern mobile browsers (including iOS Safari and different Android browsers).
mobileWebkit Boolean true for mobile webkit-based browsers.
mobileOpera Boolean true for mobile Opera.
touch Boolean true for all browsers on touch devices.
msTouch Boolean true for browsers with Microsoft touch model (e.g. IE10).
retina Boolean true for devices with Retina screens.

Util

Various utility functions, used by Leaflet internally.

Methods

Method Returns Description
extend( <Object> dest, <Object> src?.. ) Object Merges the properties of the src object (or multiple objects) into dest object and returns the latter. Has an L.extend shortcut.
bind( <Function> fn, <Object> obj, <Any> arg1?, <Any> arg2?, <Any> arg3?, … ) Function Returns a function which executes function fn with the given scope obj (so that this keyword refers to obj inside the function code). The arguments received by the bound function will be any arguments passed when binding the function, followed by any arguments passed when invoking the bound function. Has an L.bind shortcut. Works exactly like Function.prototype.bind in modern browsers compliant with ECMAScript 5.
stamp( <Object> obj ) String Applies a unique key to the object and returns that key. Has an L.stamp shortcut.
requestAnimFrame( <Function> fn, <Object> context?, <Boolean> immediate?, <HTMLElement> element? ) Number Schedules fn to be executed when the browser repaints. When immediate is set, fn is called immediately if the browser doesn't have native support for requestAnimationFrame, otherwise it's delayed. Returns an id that can be used to cancel the request
cancelAnimFrame( <Number> id ) - Cancels a previous request to requestAnimFrame.
throttle( <Function> fn, <Number> time, <Object> context? ) Function Returns a wrapper around the function fn that makes sure it's called not more often than a certain time interval time (in milliseconds), but as fast as possible otherwise (for example, it is used for checking and requesting new tiles while dragging the map), optionally passing the scope (context) in which the function will be called.
falseFn() Function Returns a function which always returns false.
formatNum( <Number> num, <Number> digits ) Number Returns the number num rounded to digits decimals.
wrapNum( <Number> num, <Array> range, <Boolean> includeMax ) Number Returns the number num modulo range in such a way so it lies within range[0] and range[1]. The returned value will be always smaller than range[1] unless includeMax is set to true.
splitWords( <String> str ) String[] Trims and splits the string on whitespace and returns the array of parts.
setOptions( <Object> obj, <Object> options ) Object Merges the given properties to the options of the obj object, returning the resulting options. See Class options. Has an L.setOptions shortcut.
getParamString( <Object> obj ) String Converts an object into a parameter URL string, e.g. {a: "foo", b: "bar"} translates to '?a=foo&b=bar'.
template( <String> str, <Object> data ) String Simple templating facility, accepts a template string of the form 'Hello {a}, {b}' and a data object like {a: 'foo', b: 'bar'}, returns evaluated string ('Hello foo, bar'). You can also specify functions instead of strings for data values — they will be evaluated passing data as an argument.
isArray( <Object> obj ) Boolean Returns true if the given object is an array.
trim( <String> str ) String Trims the whitespace from both ends of the string and returns the result.

Properties

Property Type Description
emptyImageUrl String Data URI string containing a base64-encoded empty GIF image. Used as a hack to free memory from unused images on WebKit-powered mobile devices (by setting image src to this string).

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

Creation Description
new L.Transformation( <Number> a, <Number> b, <Number> c, <Number> d ) Creates a transformation object with the given coefficients.

Methods

Method Returns Description
transform( <Point> point, <Number> scale? ) Point Returns a transformed point, optionally multiplied by the given scale. Only accepts real L.Point instances, not arrays.
untransform( <Point> point, <Number> scale? ) Point Returns the reverse transformation of the given point, optionally divided by the given scale. Only accepts real L.Point instances, not arrays.

LineUtil

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

Methods

Method Returns Description
simplify( <Point[]> points, <Number> tolerance ) Point[] Dramatically reduces the number of points in a polyline while retaining its shape and returns a new array of simplified points. Used for a huge performance boost when processing/displaying Leaflet polylines for each zoom level and also reducing visual noise. tolerance affects the amount of simplification (lesser value means higher quality but slower and with more points). Also released as a separated micro-library Simplify.js.
pointToSegmentDistance( <Point> p, <Point> p1, <Point> p2 ) Number Returns the distance between point p and segment p1 to p2.
closestPointOnSegment( <Point> p, <Point> p1, <Point> p2 ) Point Returns the closest point from a point p on a segment p1 to p2.
clipSegment( <Point> a, <Point> b, <Bounds> bounds ) - Clips the segment a to b by rectangular bounds (modifying the segment points directly!). Used by Leaflet to only show polyline points that are on the screen or near, increasing performance.

PolyUtil

Various utility functions for polygon geometries.

Methods

Method Returns Description
clipPolygon( <Point[]> points, <Bounds> bounds ) Point[] Clips the polygon geometry defined by the given points by rectangular bounds. Used by Leaflet to only show polygon points that are on the screen or near, increasing performance. Note that polygon points needs different algorithm for clipping than polyline, so there's a seperate method for it.

DomEvent

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

Methods

Method Returns Description
on( <HTMLElement> el, <String> types, <Function> fn, <Object> context? ) this Adds a listener function (fn) to a particular DOM event type of the element el. You can optionally specify the context of the listener (object the this keyword will point to). You can also pass several space-separated types (e.g. 'click dblclick').
on( <HTMLElement> el, <Object> eventMap, <Object> context? ) this Adds a set of type/listener pairs, e.g. {click: onClick, mousemove: onMouseMove}
off( <HTMLElement> el, <String> types, <Function> fn, <Object> context? ) this Removes a previously added listener function. If no function is specified, it will remove all the listeners of that particular DOM event from the element. Note that if you passed a custom context to on, you must pass the same context to off in order to remove the listener.
off( <HTMLElement> el, <Object> eventMap, <Object> context? ) this Removes a set of type/listener pairs.
addListener( <HTMLElement> el, <String> types, <Function> fn, <Object> context? ) this Alias to on.
removeListener( <HTMLElement> el, <String> types, <Function> fn, <Object> context? ) this Alias to off.
stopPropagation( <DOMEvent> e ) this Stop the given event from propagation to parent elements. Used inside the listener functions:
L.DomEvent.addListener(div, 'click', function (e) {
	L.DomEvent.stopPropagation(e);
});
preventDefault( <DOMEvent> e ) this Prevents the default action of the event from happening (such as following a link in the href of the a element, or doing a POST request with page reload when form is submitted). Use it inside listener functions.
stop( <DOMEvent> e ) this Does stopPropagation and preventDefault at the same time.
disableClickPropagation( <HTMLElement> el ) this Adds stopPropagation to the element's 'click', 'doubleclick', 'mousedown' and 'touchstart' events.
getMousePosition( <DOMEvent> e, <HTMLElement> container? ) Point Gets normalized mouse position from a DOM event relative to the container or to the whole page if not specified.
getWheelDelta( <DOMEvent> e ) Number Gets normalized wheel delta from a mousewheel DOM event.

DomUtil

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

>>>>>>> more layer docs

Methods

Method Returns Description
get( <String or HTMLElement> id ) HTMLElement Returns an element with the given id if a string was passed, or just returns the element if it was passed directly.
getStyle( <HTMLElement> el, <String> style ) String Returns the value for a certain style attribute on an element, including computed values or values set through CSS.
create( <String> tagName, <String> className, <HTMLElement> container? ) HTMLElement Creates an element with tagName, sets the className, and optionally appends it to container element.
remove( <HTMLElement> el ) - Removes el from its parent element.
empty( <HTMLElement> el ) - Removes all of el's children elements from el.
disableTextSelection() - Makes sure text cannot be selected, for example during dragging.
enableTextSelection() - Makes text selection possible again.
hasClass( <HTMLElement> el, <String> name ) Boolean Returns true if the element class attribute contains name.
falseFn() Function Always returns false.
addClass( <HTMLElement> el, <String> name ) - Adds name to the element's class attribute.
removeClass( <HTMLElement> el, <String> name ) - Removes name from the element's class attribute.
getClass( <Element> el ) <String> Returns the element's CSS class (for HTML elements) or SVG class (for SVG elements).
setClass( <HTMLElement> el, <String> name ) - Sets the element's CSS class (for HTML elements) or SVG class (for SVG elements).
setOpacity( <HTMLElement> el, <Number> value ) - Set the opacity of an element (including old IE support). Value must be from 0 to 1.
testProp( <String[]> props ) String or false Goes through the array of style names and returns the first name that is a valid style name for an element. If no such name is found, it returns false. Useful for vendor-prefixed styles like transform.
setTransform( <HTMLElement> el, <Point> offset, <Number> scale? ) - Resets the 3D CSS transform of el so it is translated by offset and optionally scaled by scale. Does not have an effect if the browser doesn't support 3D CSS transforms.
setPosition( <HTMLElement> el, <Point> point ) - Sets the position of an element to coordinates specified by point, using CSS translate or top/left positioning depending on the browser (used by Leaflet internally to position its layers).
getPosition( <HTMLElement> el ) Point Returns the coordinates of an element previously positioned with setPosition.
disableImageDrag() - Prevents the user from generating dragstart DOM events, usually generated when the user drags an image. Used internally by Leaflet to override the behaviour of any click-and-drag interaction on the map. Affects drag interactions on the whole document.
enableImageDrag() - Cancels the effects of a previous L.DomUtil.disableImageDrag.
preventOutline( <HTMLElement> el ) - Makes the outline of the element el invisible. Used internally by Leaflet to prevent focusable elements from displaying an outline when the user performs a drag interaction on them.
restoreOutline() - Cancels the effects of a previous L.DomUtil.preventOutline.

Properties

Property Type Description
TRANSITION String Vendor-prefixed transition style name (e.g. 'webkitTransition' for WebKit).
TRANSFORM String Vendor-prefixed transform style name.

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

Creation Description
new L.PosAnimation() Creates a PosAnimation object.

Methods

Method Returns Description
run( <HTMLElement> element, <Point> newPos, <Number> duration?, <Number> easeLinearity? ) this Run an animation of a given element to a new position, optionally setting duration in seconds (0.25 by default) and easing linearity factor (3rd argument of the cubic bezier curve, 0.5 by default)

Events

You can subscribe to the following events using these methods.

Event Data Description
start Event Fired when the animation starts.
step Event Fired continuously during the animation.
end Event Fired when the animation ends.

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

Creation Description
new L.Draggable( <HTMLElement> element, <HTMLElement> dragHandle? ) Creates a Draggable object for moving the given element when you start dragging the dragHandle element (equals the element itself by default).

Events

You can subscribe to the following events using these methods.

Event Data Description
dragstart Event Fired when the dragging starts.
predrag Event Fired continuously during dragging before each corresponding update of the element position.
drag Event Fired continuously during dragging.
dragend DragEndEvent Fired when the dragging ends.

Methods

Method Returns Description
enable() - Enables the dragging ability.
disable() - Disables the dragging ability.

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).

 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, …);

Evented

When creating a plugin you may want your code to have access to the event methods. By extending the Evented class you can create a class which inherits event-related methods like on, off and fire

MyEventedClass = L.Evented.extend({
	fire: function(){
		this.fire('custom', {
			// you can attach optional data to an event as an object
		});
	}
});

var myEvents = new MyEventedClass();

myEvents.on('custom', function(e){
	// e.type will  be 'custom'
	// anything else you passed in the
});

myEvents.fire();
You can still use the old-style `L.Mixin.Events` for backward compatibility.
// this class will include all event methods
MyEventedClass = L.Class.extend({
	includes: L.Mixin.Events
});

Layer

The base class for all Leaflet layers that implements basic shared methods and functionality. Can be extended to create custom layers by extending L.Layer and implementing the onAdd and onRemove methods.

Implementing Custom Layers

Custom layers should extend the L.Layer base class. L.Layer provides convenience methods for your layer like addTo(map), removeFrom(map) and getPane().

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.

Methods

Every layer should extend from L.Layer and implement the following methods:

Method Returns Description
onAdd(<Map> map) this Should contain code that creates DOM elements for the overlay, adds them to map panes where they should belong and puts listeners on relevant map events. Called on map.addLayer(layer).
onRemove(<Map> map) this Should contain all clean up code that removes the overlay's elements from the DOM and removes listeners previously added in onAdd. Called on map.removeLayer(layer).
getEvents() Object This optional method should return an object like { viewreset: this._reset }for addEventListener. These events will be automatically added and removed from the map with your layer.

Custom Layer Example

Here's how a custom layer implementation usually looks:

var MyCustomLayer = L.Layer.extend({

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

	// these events will be added and removed from the map with the layer
	getEvents: function(){
		return {
			viewreset: this._reset
		}
	},

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

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

	onRemove: function (map) {
		// remove layer's DOM elements and listeners
		this.getPane().removeChild(this._el);
	},

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

var myLayer = new MyCustomLayer(latlng).addTo(map);

Inherited Options

Classes extending from L.Layer will also inherit the following options:

Option Type Default value Description
pane String 'overlayPane' By default the layer will be added to the maps overlay pane. Overriding this option will cause the layer to be placed on another pane by default.

Inherited Events

Classes extending from L.Layer will also fire the following events:

Event Data Description
add Event Fired after the layer is added to a map.
remove Event Fired after the layer is removed from a map.

Inherited Methods

Classes extending from L.Layer will also inherit the following methods:

Method Returns Description
addTo(<Map> map) this Adds the layer to the given map.
removeFrom(<Map> map) this Removes the layer to the given map.
remove() this Removes the layer from the map it is currently active on.
getPane(<String> name?) HTMLElement Returns the HTMLElement representing the named pane on the map. Or if name is omitted the pane for this layer.

Control

Controls represents a UI element in one of the corners of the map. Implemented by zoom, attribution, scale and layers controls. Can be used to create custom controls by extending L.Control and implementing the onAdd and onRemove methods.

Methods

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

Method Returns Description
onAdd( <Map> map ) HTMLElement Should contain code that creates all the neccessary DOM elements for the control, adds listeners on relevant map events, and returns the element containing the control. Called on map.addControl(control) or control.addTo(map).
onRemove( <Map> map ) - Optional, should contain all clean up code (e.g. removes control's event listeners). Called on map.removeControl(control) or control.removeFrom(map). The control's DOM container is removed automatically.

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'}));

Options

Classes extending from L.Control will also inherit the following options:

Option Type Default Description
position String 'topright' The initial position of the control (one of the map corners). See control positions.

Inherited Methods

Classes extending from L.Control will also inherit the following methods:

Method Returns Description
setPosition( <String> position ) this Sets the position of the control. See control positions.
getPosition() String Returns the current position of the control.
addTo( <Map> map ) this Adds the control to the map.
removeFrom( <Map> map ) this Removes the control from the map.
getContainer() HTMLElement Returns the HTML container of the control.

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.

Position Description
'topleft' Top left of the map.
'topright' Top right of the map.
'bottomleft' Bottom left of the map.
'bottomright' Bottom right of the map.

Handler

Implemented by map interaction handlers.

Method Returns Description
enable() - Enables the handler.
disable() - Disables the handler.
enabled() Boolean Returns true if the handler is enabled.

Projection

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

Properties

Property Type Description
bounds LatLngBounds The bounds where the projection is valid

Methods

Method Returns Description
project( <LatLng> latlng ) Point Projects geographical coordinates into a 2D point.
unproject( <Point> point ) LatLng The inverse of project. Projects a 2D point into geographical location.

Defined Projections

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

Projection Description
L.Projection.SphericalMercator Spherical Mercator projection — the most common projection for online maps, used by almost all free and commercial tile providers. Assumes that Earth is a sphere. Used by the EPSG:3857 CRS.
L.Projection.Mercator Elliptical Mercator projection — more complex than Spherical Mercator. Takes into account that Earth is a geoid, not a perfect sphere. Used by the EPSG:3395 CRS.
L.Projection.LonLat Equirectangular, or Plate Carree projection — the most simple projection, mostly used by GIS enthusiasts. Directly maps x as longitude, and y as latitude. Also suitable for flat worlds, e.g. game maps. Used by the EPSG:3395 and Simple CRS.

CRS

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

Method Returns Description
latLngToPoint( <LatLng> latlng, <Number> zoom ) Point Projects geographical coordinates on a given zoom into pixel coordinates.
pointToLatLng( <Point> point, <Number> zoom ) LatLng The inverse of latLngToPoint. Projects pixel coordinates on a given zoom into geographical coordinates.
project( <LatLng> latlng ) Point Projects geographical coordinates into coordinates in units accepted for this CRS (e.g. meters for EPSG:3857, for passing it to WMS services).
unproject( <Point> point ) LatLng Given a projected coordinate returns the corresponding LatLng. The inverse of project.
scale( <Number> zoom ) Number Returns the scale used when transforming projected coordinates into pixel coordinates for a particular zoom. For example, it returns 256 * 2^zoom for Mercator-based CRS.
getProjectedBounds( <Number> zoom ) Bounds Returns the projection's bounds scaled and transformed for the provided zoom.
distance( <LatLng> latlng1, <LatLng> latlng2 ) Number Returns the distance in meters between two geographic coordinates in this CRS.
wrapLatLng( <LatLng> latlng ) LatLng Returns a LatLng where lat and lng has been wrapped according to the CRS's wrapLat and wrapLng properties, if they are outside the CRS's bounds.

Properties

Property Type Description
projection IProjection Projection that this CRS uses.
transformation Transformation Transformation that this CRS uses to turn projected coordinates into screen coordinates for a particular tile service.
code String Standard code name of the CRS passed into WMS services (e.g. 'EPSG:3857').
wrapLat Number[] Latitude bounds, lower followed by upper, at which latitudes should wrap around, or null to disable wrapping
wrapLng Number[] Longitude bounds, lower followed by upper, at which longitudes should wrap around, or null to disable wrapping
infinite Boolean true if the CRS bounds should be ignored; coordinates in an infinite CRS will not be wrapped

Defined CRS

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

Projection Description
L.CRS.Earth Serves as the base for CRS that are global such that they cover the earth. Can only be used as the base for other CRS and cannot be used directly, since it does not have a code, projection or transformation.
L.CRS.EPSG3857 The most common CRS for online maps, used by almost all free and commercial tile providers. Uses Spherical Mercator projection. Set in by default in Map's crs option.
L.CRS.EPSG4326 A common CRS among GIS enthusiasts. Uses simple Equirectangular projection.
L.CRS.EPSG3395 Rarely used by some commercial tile providers. Uses Elliptical Mercator projection.
L.CRS.Simple A simple CRS that maps longitude and latitude into x and y directly. May be used for maps of flat surfaces (e.g. game maps). Note that the y axis should still be inverted (going from bottom to top).

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

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.

property type description
type String The event type (e.g. 'click').
target Object The object that fired the event.

MouseEvent

property type description
latlng LatLng The geographical point where the mouse event occured.
layerPoint Point Pixel coordinates of the point where the mouse event occured relative to the map layer.
containerPoint Point Pixel coordinates of the point where the mouse event occured relative to the map сontainer.
originalEvent DOMMouseEvent The original DOM mouse event fired by the browser.

LocationEvent

property type description
latlng LatLng Detected geographical location of the user.
bounds LatLngBounds Geographical bounds of the area user is located in (with respect to the accuracy of location).
accuracy Number Accuracy of location in meters.
altitude Number Height of the position above the WGS84 ellipsoid in meters.
altitudeAccuracy Number Accuracy of altitude in meters.
heading Number The direction of travel in degrees counting clockwise from true North.
speed Number Current velocity in meters per second.
timestamp Number The time when the position was acquired.

ErrorEvent

property type description
message String Error message.
code Number Error code (if applicable).

LayerEvent

property type description
layer ILayer The layer that was added or removed.

LayersControlEvent

property type description
layer ILayer The layer that was added or removed.
name String The name of the layer that was added or removed.

TileEvent

property type description
tile HTMLElement The tile element (image).

TileErrorEvent

property type description
tile HTMLElement The tile element (image).

ResizeEvent

property type description
oldSize Point The old size before resize event.
newSize Point The new size after the resize event.

GeoJSON event

property type description
layer ILayer The layer for the GeoJSON feature that is being added to the map.
properties Object GeoJSON properties of the feature.
geometryType String GeoJSON geometry type of the feature.
id String GeoJSON ID of the feature (if present).
property type description
popup Popup The popup that was opened or closed.

DragEndEvent

property type description
distance Number The distance in pixels the draggable element was moved by.

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>
Switch Description
L_PREFER_CANVAS Forces Leaflet to use the Canvas back-end (if available) for vector layers instead of SVG. This can increase performance considerably in some cases (e.g. many thousands of circle markers on the map).
L_NO_TOUCH Forces Leaflet to not use touch events even if it detects them.
L_DISABLE_3D Forces Leaflet to not use hardware-accelerated CSS 3D transforms for positioning (which may cause glitches in some rare environments) even if they're supported.

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 // contains "0.5" (or whatever version is currently in use)