Leaflet

Leaflet API reference

This reference reflects Leaflet 2.0.0-beta.5, a prerelease of Leaflet 2.0. The API can still change before 2.0.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
const map = new LeafletMap('map', {
	center: [51.505, -0.09],
	zoom: 13
});

Constructor

Constructor Description
new Map(id: String|HTMLElement, options?: Map options) Instantiates a map object given the DOM ID of a <div> element (or the element itself) and optionally an object literal with Map options. Sets role="region" and aria-label="Map" on the container unless already present.

Options

Map state options

Option Type Default Description
crs CRS EPSG3857 The Coordinate Reference System to use. Don't change this if you're not sure what it means.
center LatLng Initial geographic center of the map
zoom Number Initial map zoom level
minZoom Number Minimum zoom level of the map. If not specified and at least one GridLayer or TileLayer is in the map, the lowest of their minZoom options will be used instead.
maxZoom Number Maximum zoom level of the map. If not specified and at least one GridLayer or TileLayer is in the map, the highest of their maxZoom options will be used instead.
layers Layer[] [] Array of layers that will be added to the map initially
maxBounds LatLngBounds null When this option is set, the map restricts the view to the given geographical bounds, bouncing the user back if the user tries to pan outside the view. To set the restriction dynamically, use setMaxBounds method.
renderer Renderer The default method for drawing vector layers on the map. A new SVG renderer by default; pass new Canvas() to draw them on a canvas instead. Paths in custom panes get their own renderer for that pane, of the same class and with the same options as this one.

Animation options

Option Type Default Description
zoomAnimation Boolean true Whether the map zoom animation is enabled.
zoomAnimationThreshold Number 4 Won't animate zoom if the zoom difference exceeds this value (or 1 if the user prefers reduced motion and animate: true isn't passed).
fadeAnimation Boolean true Whether the tile and popup fade animation is enabled.
markerZoomAnimation Boolean true Whether markers animate their zoom with the zoom animation, if disabled they will disappear for the length of the animation.
transform3DLimit Number 8388608 Defines the maximum size of a CSS translation transform. The default value should not be changed unless a web browser positions layers in the wrong place after doing a large panBy.

Interaction options

Option Type Default Description
zoomSnap Number 1 Forces the map's zoom level to always be a multiple of this, particularly right after a fitBounds() or a pinch-zoom. By default, the zoom level snaps to the nearest integer; lower values (e.g. 0.5 or 0.1) allow for greater granularity. A value of 0 means the zoom level will not be snapped after fitBounds or a pinch-zoom.
zoomDelta Number 1 Controls how much the map's zoom level will change after a zoomIn(), zoomOut(), pressing + or - on the keyboard, or using the zoom controls. Values smaller than 1 (e.g. 0.5) allow for greater granularity.
trackResize Boolean true Whether the map automatically handles browser window resize to update itself.
closePopupOnClick Boolean true Set it to false if you don't want popups to close when user clicks the map.
boxZoom Boolean true Whether the map can be zoomed to a rectangular area specified by dragging the pointer while pressing the shift key.
doubleClickZoom Boolean|String 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 pointer was.
dragging Boolean true Whether the map is draggable with pointer or not.

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. Enabled by default.
inertiaDeceleration Number 3400 The rate with which the inertial movement slows down, in pixels/second².
inertiaMaxSpeed Number 1400 Max speed of the inertial movement, in pixels/second.
easeLinearity Number 0.2 The curvature factor of the inertial movement's easing, like the easeLinearity pan option.
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. A map with an infinite CRS, such as SimpleCRS, does not jump, as it has no copies of the world.
maxBoundsViscosity Number 0.0 If maxBounds is set, this option 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.

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.
keyboardPanDelta Number 80 Amount of pixels to pan when pressing an arrow key.
ariaKeyShortcuts Boolean|String false Sets the aria-keyshortcuts attribute of the map container. ARIA names keys by what they type on a given layout, so true uses the names for a US English layout, which can be wrong for pages in other languages; pass a string to set the value for your audience's layout instead.

Mouse wheel options

Option Type Default Description
scrollWheelZoom Boolean|String 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 pointer was.
wheelDebounceTime Number 40 Limits the rate at which a wheel can fire (in milliseconds). By default, the user can't zoom via wheel more often than once per 40 ms.
wheelPxPerZoomLevel Number 60 How many scroll pixels (as reported by DomEvent.getWheelDelta) mean a change of one full zoom level. Smaller values will make wheel-zooming faster (and vice versa).

Touch interaction options

Option Type Default Description
tapHold Boolean true Fires a contextmenu event on a long touch press. iOS Safari doesn't fire one natively.
tapTolerance Number 15 The max number of pixels a user can shift his finger during touch for it to be considered a valid tap.
pinchZoom Boolean|String 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. Enabled for touch-capable web browsers.
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.

Control options

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

Localization options

Option Type Default Description
translate Function A function that translates the English text Leaflet and plugins show to users, such as control titles and accessible labels, e.g. text => i18next.t(text). If it returns undefined, the text stays in English. Text is translated when it's rendered, so set it before adding controls and opening popups. You can identify translatable text in the documentation by the Translatable badge.

See Translate built-in text for an example of how to provide translations.

You can also use the plugin Leaflet.Translations, which provides predefined translations for various languages.

Events

Layer events

Event Data Description
baselayerchange LayersControlEvent Fired when the base layer is changed through the layers control.
overlayadd LayersControlEvent Fired when an overlay is selected through the layers control.
overlayremove LayersControlEvent Fired when an overlay is deselected through the layers control.
layeradd LayerEvent Fired when a new layer is added to the map.
layerremove LayerEvent Fired when some layer is removed from the map

Popup events

Event Data Description
popupopen PopupEvent Fired when a popup is opened in the map
popupclose PopupEvent Fired when a popup in the map is closed
autopanstart Event Fired when the map starts autopanning when opening a popup.

Tooltip events

Event Data Description
tooltipopen TooltipEvent Fired when a tooltip is opened in the map.
tooltipclose TooltipEvent Fired when a tooltip in the map is closed.

Map state change events

Event Data Description
resize ResizeEvent Fired when the map is resized.
unload Event Fired when the map is destroyed with remove method.
viewprereset ViewPreResetEvent Fired right before viewreset, while the map still has its old view, with the new center and zoom.
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.
load Event Fired when the map is initialized (when its center and zoom are set for the first time).
zoomstart ViewChangeEvent Fired when the map zoom is about to change (e.g. before zoom animation).
movestart ViewChangeEvent Fired when the view of the map starts changing (e.g. user starts dragging the map).
zoom ViewChangeEvent Fired repeatedly during any change in zoom level, including zoom and fly animations.
move ViewChangeEvent Fired repeatedly during any movement of the map, including pan and fly animations.
zoomend ViewChangeEvent Fired when the map zoom changed, after any animations.
moveend ViewChangeEvent Fired when the center of the map stops changing (e.g. user stopped dragging the map or after non-centered zoom).
worldcopyjump WorldCopyJumpEvent Fired when worldCopyJump moves the map pane by one or more world widths.
zoomlevelschange Event Fired when the number of zoomlevels on the map is changed due to adding or removing a layer.

Location events

Event Data Description
locationerror ErrorEvent Fired when geolocation (using the locate method) failed.
locationfound LocationEvent Fired when geolocation (using the locate method) went successfully.

Interaction events

Event Data Description
click PointerEvent Fired when the user clicks (or taps) the map.
dblclick PointerEvent Fired when the user double-clicks (or double-taps) the map.
pointerdown PointerEvent Fired when the user pushes the pointer on the map.
pointerup PointerEvent Fired when the user releases the pointer on the map.
pointerover PointerEvent Fired when the pointer enters the map.
pointerout