Map

This section describes the central class of the maps API which is used to create a map on a page and manipulate it.

DG.Map

Usage example

Initialize the map on the "map" div with a given center and zoom:

var map = DG.map('map', {
    center: [54.98, 82.89],
    zoom: 13,
});

Creation

Factory	Description
`DG.map( <String> id, <Map options> options? )`	Instantiates a map object given the DOM ID of a `<div>` element and optionally an object literal with `Map options`.
`DG.map( <HTMLElement> el, <Map options> options?)`	Instantiates a map object given an instance of a `<div>` HTML element and optionally an object literal with `Map options`.

Options

Option	Type	Default	Description
`preferCanvas`	`Boolean`	`false`	Whether `Path`s should be rendered on a `Canvas` renderer. By default, all `Path`s are rendered in a `SVG` renderer.

Control Options

Option	Type	Default	Description
`zoomControl`	`Boolean`	`true`	Whether a zoom control is added to the map by default.
`fullscreenControl`	`Boolean`	`true`	Whether a fullscreen control is added to the map by default.

Interaction Options

Option	Type	Default	Description
`closePopupOnClick`	`Boolean`	`true`	Set it to `false` if you don't want popups to close when user clicks the map.
`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.
`boxZoom`	`Boolean`	`true`	Whether the map can be zoomed to a rectangular area specified by dragging the mouse while pressing the shift key.
`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.
`dragging`	`Boolean`	`true`	Whether the map be draggable with mouse/touch or not.
`geoclicker`	`Boolean \| Object`	`false`
`projectDetector`	`Boolean`	`true`
`tilesCheck`	`Boolean`	`true`
`museum`	`Boolean`	`true`	Whether the message about unsupported browser will be displayed.

Map State Options

Option	Type	Default	Description
`center`	`LatLng`	`undefined`	Initial geographic center of the map
`zoom`	`Number`	`undefined`	Initial map zoom level
`minZoom`	`Number`	`undefined`	Minimum zoom level of the map. Overrides any `minZoom` option set on map layers.
`maxZoom`	`Number`	`undefined`	Maximum zoom level of the map. Overrides any `maxZoom` option set on map layers.
`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 when he 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. `DG.SVG` or `DG.Canvas` by default depending on browser support.
`poi`	`Boolean`	`true`
`currentLang`	`string`	`''`	Language of user interface (see Localization)

Animation Options

Option	Type	Default	Description
`fadeAnimation`	`Boolean`	`true`	Whether the tile fade animation is enabled. By default it's enabled in all browsers that support CSS3 Transitions except Android.
`markerZoomAnimation`	`Boolean`	`true`	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.
`transform3DLimit`	`Number`	`2^23`	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`.
`zoomAnimation`	`Boolean`	`true`	Whether the map 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.

Panning Inertia Options

Option	Type	Default	Description
`inertia`	`Boolean`	`*`	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 unless running on old Android devices.
`inertiaDeceleration`	`Number`	`3000`	The rate with which the inertial movement slows down, in pixels/second².
`inertiaMaxSpeed`	`Number`	`Infinity`	Max speed of the inertial movement, in pixels/second.
`easeLinearity`	`Number`	`0.2`
`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.
`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.

Mousewheel 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 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.
`wheelPxPerZoomLevel`	`Number`	`50`	How many scroll pixels (as reported by DG.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
`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.
`touchZoom`	`Boolean`	`*`	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 except for old Androids.
`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.

Events

Layer events

Event	Data	Description
`layeradd`	`LayerEvent`	Fired when a new layer is added to the map.
`layerremove`	`LayerEvent`	Fired when some layer is removed from the map

Map state change events

Event	Data	Description
`zoomlevelschange`	`Event`	Fired when the number of zoomlevels on the map is changed due to adding or removing a layer.
`resize`	`Event`	Fired when the map is resized.
`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.
`load`	`Event`	Fired when the map is initialized (when its center and zoom are set for the first time).
`zoomstart`	`Event`	Fired when the map zoom is about to change (e.g. before zoom animation).
`movestart`	`Event`	Fired when the view of the map starts changing (e.g. user starts dragging the map).
`zoom`	`Event`	Fired repeteadly during any change in zoom level, including zoom and fly animations.
`move`	`Event`	Fired repeteadly during any movement of the map, including pan and fly animations.
`zoomend`	`Event`	Fired when the map has changed, after any animations.
`moveend`	`Event`	Fired when the center of the map stops changing (e.g. user stopped dragging the map).
`projectchange`	`ProjectEvent`
`projectleave`	`ProjectEvent`
`entranceshow`	`Event`
`entrancehide`	`Event`
`poihover`	`MetaEvent`
`poileave`	`MetaEvent`
`langchange`	`LangEvent`

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`		Fired when the map starts autopanning when opening a popup.

Interaction events

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).
`keypress`	`Event`	Fired when the user presses a key from the keyboard while the map is focused.
`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).

Animation Events

Event	Data	Description
`zoomanim`	`ZoomAnimEvent`	Fired on every frame of a zoom animation

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.

Methods

Method	Returns	Description
`getRenderer( <Path> layer)`	`Renderer`	Returns the instance of `Renderer` that should be used to render the given `Path`. It will ensure that the `renderer` options of the map and paths are respected, and that the renderers do exist on the map.

Methods for Layers and Controls

Method	Returns	Description
`addLayer( <Layer> layer)`	`this`	Adds the given layer to the map
`removeLayer( <Layer> layer)`	`this`	Removes the given layer from the map.
`hasLayer( <Layer> 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\|HTMLElement> content, <LatLng> latlng, <Popup options> options?)`	`this`	Creates a popup with the specified content and 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( <Control> control)`	`this`	Adds the given control to the map
`removeControl( <Control> control)`	`this`	Removes the given control from the map

Methods for modifying map state

Method	Returns	Description
`setView( <LatLnt> 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/Pan options> options)`	`this`	Sets the zoom of the map.
`zoomIn( <Number> delta?, <Zoom options> options?)`	`this`	Increases the zoom of the map by `delta` (`zoomDelta` by default).
`zoomOut( <Number> delta?, <Zoom options> options?)`	`this`	Decreases the zoom of the map by `delta` (`zoomDelta` by default).
`setZoomAround( <LatLng> latlng, <Number> zoom, <Zoom options> options)`	`this`	Zooms the map while keeping a specified geographical point on the map stationary (e.g. used internally for scroll zoom and double-click zoom).
`setZoomAround( <Point> offset, <Number> zoom, <Zoom options> options)`	`this`	Zooms the map while keeping a specified pixel on the map (relative to the top-left corner) stationary.
`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.
`panBy( <Point> offset)`	`this`	Pans the map by a given number of pixels (animated).
`setMaxBounds( <Bounds> bounds)`	`this`	Restricts the map view to the given bounds (see the maxBounds option).
`setMinZoom(<Number> zoom)`	`this`	Sets the lower limit for the available zoom levels (see the minZoom option).
`setMaxZoom(<Number> zoom)`	`this`	Sets the upper limit for the available zoom levels (see the maxZoom option).
`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.
`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.
`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.
`stop()`	`this`	Stops the currently running `panTo` or `flyTo` animation, if any.
`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`.
`setLang( <String> lang )`	`String`

Other Methods

Method	Returns	Description
`addHandler( <String> name, <Function> HandlerClass)`	`this`	Adds a new `Handler` to the map, given its name and constructor function.
`remove()`	`this`	Destroys the map and clears all related event listeners.
`createPane( <String> name, <HTMLElement> container?)`	`HTMLElement`	Creates a new map pane with the given name if it doesn't exist already, then returns it. The pane is created as a children of `container`, or as a children of the main map pane if not set.
`getPane(<String\|HTMLElement> pane)`	`HTMLElement`	Returns a map pane, given its name or its HTML element (its identity).
`getPanes()`	`Object`	Returns a plain object containing the names of all panes as keys and the panes as values.
`getContainer()`	`HTMLElement`	Returns the HTML element that contains the map.
`whenReady( <Function> fn, <Object> context?)`	`this`	Runs the given function `fn` when the map gets initialized with a view (center and zoom) and at least one layer, or immediately if it's already initialized, optionally passing a function context.

Methods for Getting Map State

Method	Returns	Description
`getCenter()`	`LatLng`	Returns the geographical center of the map view
`getZoom()`	`Number`	Returns the current zoom level of the map view
`getBounds()`	`LatLngBounds`	Returns the geographical bounds visible in the current map view
`getMinZoom()`	`Number`	Returns the minimum zoom level of the map (if set in the `minZoom` option of the map or of any layers), or `0` by default.
`getMaxZoom()`	`Number`	Returns the maximum zoom level of the map (if set in the `maxZoom` option of the map or of any layers).
`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 (in pixels).
`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 level is used.
`getLang()`	`String`

Conversion Methods

Method	Returns	Description
`getZoomScale( <Number> toZoom, <Number> fromZoom)`	`Number`	Returns the scale factor to be applied to a map transition from zoom level `fromZoom` to `toZoom`. Used internally to help with zoom animations.
`getScaleZoom( <Number> scale, <Number> fromZoom)`	`Number`	Returns the zoom level that the map would end up at, if it is at `fromZoom` level and everything is scaled by a factor of `scale`. Inverse of `getZoomScale`.
`project( <LatLng> latlng, <Number> zoom)`	`Point`	Projects a geographical coordinate `LatLng` according to the projection of the map's CRS, then scales it according to `zoom` and the CRS's `Transformation`. The result is pixel coordinate relative to the CRS origin.
`unproject( <Point> point, <Number> zoom)`	`LatLng`	Inverse of `project`.
`layerPointToLatLng( <Point> point)`	`LatLng`	Given a pixel coordinate relative to the origin pixel, returns the corresponding geographical coordinate (for the current zoom level).
`latLngToLayerPoint( <LatLng> latlng)`	`Point`	Given a geographical coordinate, returns the corresponding pixel coordinate relative to the origin pixel.
`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. By default this means longitude is wrapped around the dateline so its value is between -180 and +180 degrees.
`distance( <LatLng> latlng1, <LatLng> latlng2)`	`Number`	Returns the distance between two geographical coordinates according to the map's CRS. By default this measures distance in meters.
`containerPointToLayerPoint( <Point> point)`	`Point`	Given a pixel coordinate relative to the map container, returns the corresponding pixel coordinate relative to the origin pixel.
`layerPointToContainerPoint( <Point> point)`	`Point`	Given a pixel coordinate relative to the origin pixel, returns the corresponding pixel coordinate relative to the map container.
`containerPointToLatLng( <Point> point)`	`Point`	Given a pixel coordinate relative to the map container, returns the corresponding geographical coordinate (for the current zoom level).
`latLngToContainerPoint( <LatLng> latlng)`	`Point`	Given a geographical coordinate, returns the corresponding pixel coordinate relative to the map container.
`mouseEventToContainerPoint( <MouseEvent> ev)`	`Point`	Given a MouseEvent object, returns the pixel coordinate relative to the map container where the event took place.
`mouseEventToLayerPoint( <MouseEvent> ev)`	`Point`	Given a MouseEvent object, returns the pixel coordinate relative to the origin pixel where the event took place.
`mouseEventToLatLng( <MouseEvent> ev)`	`LatLng`	Given a MouseEvent object, returns geographical coordinate where the event took place.

Geolocation methods

Method	Returns	Description
`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}`.

Methods inherited from Evented

Methods inherited from Evented see here.

Properties

Handlers

Property	Type	Description
`boxZoom`	`Handler`	Box (shift-drag with mouse) zoom handler.
`doubleClickZoom`	`Handler`	Double click zoom handler.
`dragging`	`Handler`	Map dragging handler (by both mouse and touch).
`keyboard`	`Handler`	Keyboard navigation handler.
`scrollWheelZoom`	`Handler`	Scroll wheel zoom handler.
`tap`	`Handler`	Mobile touch hacks (quick tap and touch hold) handler.
`touchZoom`	`Handler`	Touch zoom handler.
`geoclicker`	`Handler`
`projectDetector`	`Handler`
`zoomControl`	`Control.Zoom`
`fullscreenControl`	`Control.FullScreen`
`rulerControl`	`Control.Ruler`
`trafficControl`	`Control.Traffic`
`baseLayer`	`TileLayer`

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.getPanes methods. New panes can be created with the map.createPane method. Every map has the following default 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.

Locate options

Some of the geolocation methods for Map take in an options parameter. This is a plain javascript object with the following optional components:

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 options

Some of the Map methods which modify the zoom level take in an options parameter. This is a plain javascript object with the following optional components:

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.

Pan options

Some of the Map methods which modify the center of the map take in an options parameter. This is a plain javascript object with the following optional components:

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, in seconds.
`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/pan options

Options inherited from Zoom options

Options inherited from Pan options

FitBounds options

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