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( |
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 |
|
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. |
Mouse wheel options
| Option | Type | Default | Description |
|---|---|---|---|
scrollWheelZoom |
|
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
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 |