Maps

Map Class

The Map object represents the map on your page. It exposes methods and properties that enable you to programmatically change the map, and fires events as users interact with it.

You create a Map by specifying a container and other options. Then NMaps GL JS initializes the map on the page and returns your Map object.

Extends Evented.

new Map(options: Object)

Parameters

options(Object)

Name	Description
options.container `(HTMLElement \| string)`	The HTML element in which NMaps GL JS will render the map, or the element's string `id` . The specified element must have no children.
options.minZoom `number` default: `2`	The minimum zoom level of the map (2-24).
options.maxZoom `number` default: `22`	The maximum zoom level of the map (2-24).
options.minPitch `number` default: `0`	The minimum pitch of the map (0-60).
options.maxPitch `number` default: `60`	The maximum pitch of the map (0-60).
options.style `(Object \| string)?`	The map's style. This must be a style ID or a URL to get JSON style. The available style IDs are: 'Streets', 'Light', 'Dark' and 'Satellite'. This parameter is optional and the default value is 'Streets'.
options.hash `(boolean \| string)` default: `false`	If `true` , the map's position (zoom, center latitude, center longitude, bearing, and pitch) will be synced with the hash fragment of the page's URL. For example, `http://path/to/my/page.html#2.59/39.26/53.07/-24.1/60` . An additional string may optionally be provided to indicate a parameter-styled hash, e.g. http://path/to/my/page.html#map=2.59/39.26/53.07/-24.1/60&foo=bar , where foo is a custom parameter and bar is an arbitrary hash distinct from the map hash.
options.interactive `boolean` default: `true`	If `false` , no mouse, touch, or keyboard listeners will be attached to the map, so it will not respond to interaction.
options.bearingSnap `number` default: `7`	The threshold, measured in degrees, that determines when the map's bearing will snap to north. For example, with a `bearingSnap` of 7, if the user rotates the map within 7 degrees of north, the map will automatically snap to exact north.
options.pitchWithRotate `boolean` default: `true`	If `false` , the map's pitch (tilt) control with "drag to rotate" interaction will be disabled.
options.clickTolerance `number` default: `3`	The max number of pixels a user can shift the mouse pointer during a click for it to be considered a valid click (as opposed to a mouse drag).
options.attributionControl `boolean` default: `true`	If `true` , an AttributionControl will be added to the map.
options.customAttribution `(string \| Array<string>)?`	String or strings to show in an AttributionControl . Only applicable if `options.attributionControl` is `true` .
options.logoPosition `string` default: `'bottom-left'`	A string representing the position of the NMaps wordmark on the map. Valid options are `top-left` , `top-right` , `bottom-left` , `bottom-right` .
options.failIfMajorPerformanceCaveat `boolean` default: `false`	If `true` , map creation will fail if the performance of NMaps GL JS would be dramatically worse than expected (i.e. a software renderer would be used).
options.preserveDrawingBuffer `boolean` default: `false`	If `true` , the map's canvas can be exported to a PNG using `map.getCanvas().toDataURL()` . This is `false` by default as a performance optimization.
options.antialias `boolean?`	If `true` , the gl context will be created with MSAA antialiasing, which can be useful for antialiasing custom layers. this is `false` by default as a performance optimization.
options.refreshExpiredTiles `boolean` default: `true`	If `false` , the map won't attempt to re-request tiles once they expire per their HTTP `cacheControl` / `expires` headers.
options.maxBounds `LngLatBoundsLike?`	If set, the map will be constrained to the given bounds.
options.scrollZoom `(boolean \| Object)` default: `true`	If `true` , the "scroll to zoom" interaction is enabled. An `Object` value is passed as options to ScrollZoomHandler#enable .
options.boxZoom `boolean` default: `true`	If `true` , the "box zoom" interaction is enabled (see BoxZoomHandler ).
options.dragRotate `boolean` default: `true`	If `true` , the "drag to rotate" interaction is enabled (see DragRotateHandler ).
options.dragPan `(boolean \| Object)` default: `true`	If `true` , the "drag to pan" interaction is enabled. An `Object` value is passed as options to DragPanHandler#enable .
options.rightClick `boolean` default: `true`	If `true` , the right click interaction is enabled. A Menu with options to interact with map will be displayed.
options.keyboard `boolean` default: `true`	If `true` , keyboard shortcuts are enabled (see KeyboardHandler ).
options.doubleClickZoom `boolean` default: `true`	If `true` , the "double click to zoom" interaction is enabled (see DoubleClickZoomHandler ).
options.touchZoomRotate `(boolean \| Object)` default: `true`	If `true` , the "pinch to rotate and zoom" interaction is enabled. An `Object` value is passed as options to TouchZoomRotateHandler#enable .
options.touchPitch `(boolean \| Object)` default: `true`	If `true` , the "drag to pitch" interaction is enabled. An `Object` value is passed as options to TouchPitchHandler#enable .
options.trackResize `boolean` default: `true`	If `true` , the map will automatically resize when the browser window resizes.
options.center `LngLatLike` default: `[0,0]`	The inital geographical centerpoint of the map. If `center` is not specified in the constructor options, NMaps GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to `[0, 0]` Note: NMaps GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match GeoJSON.
options.zoom `number` default: `0`	The initial zoom level of the map. If `zoom` is not specified in the constructor options, NMaps GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to `0` .
options.bearing `number` default: `0`	The initial bearing (rotation) of the map, measured in degrees counter-clockwise from north. If `bearing` is not specified in the constructor options, NMaps GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to `0` .
options.pitch `number` default: `0`	The initial pitch (tilt) of the map, measured in degrees away from the plane of the screen (0-60). If `pitch` is not specified in the constructor options, NMaps GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to `0` .
options.bounds `LngLatBoundsLike?`	The initial bounds of the map. If `bounds` is specified, it overrides `center` and `zoom` constructor options.
options.fitBoundsOptions `Object?`	A Map#fitBounds options object to use only when fitting the initial `bounds` provided above.
options.renderWorldCopies `boolean` default: `true`	If `true` , multiple copies of the world will be rendered side by side beyond -180 and 180 degrees longitude. If set to `false` : When the map is zoomed out far enough that a single representation of the world does not fill the map's entire container, there will be blank space beyond 180 and -180 degrees longitude. Features that cross 180 and -180 degrees longitude will be cut in two (with one portion on the right edge of the map and the other on the left edge of the map) at every zoom level.
options.maxTileCacheSize `number` default: `null`	The maximum number of tiles stored in the tile cache for a given source. If omitted, the cache will be dynamically sized based on the current viewport.
options.localIdeographFontFamily `string` default: `'sans-serif'`	Defines a CSS font-family for locally overriding generation of glyphs in the 'CJK Unified Ideographs', 'Hiragana', 'Katakana' and 'Hangul Syllables' ranges. In these ranges, font settings from the map's style will be ignored, except for font-weight keywords (light/regular/medium/bold). Set to `false` , to enable font settings from the map's style for these glyph ranges. The purpose of this option is to avoid bandwidth-intensive glyph server requests. (See Use locally generated ideographs .)
options.transformRequest `RequestTransformFunction` default: `null`	A callback run before the Map makes a request for an external URL. The callback can be used to modify the url, set headers, or set the credentials property for cross-origin requests. Expected to return an object with a `url` property and optionally `headers` and `credentials` properties.
options.collectResourceTiming `boolean` default: `false`	If `true` , Resource Timing API information will be collected for requests made by GeoJSON and Vector Tile web workers (this information is normally inaccessible from the main Javascript thread). Information will be returned in a `resourceTiming` property of relevant `data` events.
options.fadeDuration `number` default: `300`	Controls the duration of the fade-in/fade-out animation for label collisions, in milliseconds. This setting affects all symbol layers. This setting does not affect the duration of runtime styling transitions or raster tile cross-fading.
options.crossSourceCollisions `boolean` default: `true`	If `true` , symbols from multiple sources can collide with each other during collision detection. If `false` , collision detection is run separately for the symbols in each source.
options.accessToken `string` default: `null`	If specified, map will use this token instead of the one defined in nmapsgl.accessToken.
options.locale `Object` default: `null`	A patch to apply to the default localization table for UI strings, e.g. control tooltips. The `locale` object maps namespaced UI string IDs to translated strings in the target language; see `src/ui/default_locale.js` for an example with all supported string IDs. The object may specify all UI strings (thereby adding support for a new translation) or only a subset of strings (thereby patching the default translation table).

Example

const map = new nmapsgl.Map({
container: 'map',
center: [-122.420679, 37.772537],
zoom: 13,
style: style_object,
hash: true,
transformRequest: (url, resourceType)=> {
if(resourceType === 'Source' && url.startsWith('http://myHost')) {
return {
url: url.replace('http', 'https'),
headers: { 'my-custom-header': true},
credentials: 'include'  // Include cookies for cross-origin requests
}
}
}
});

LngLat

A LngLat object represents a given longitude and latitude coordinate, measured in degrees. These coordinates are based on the WGS84 (EPSG:4326) standard.

NMaps GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match the GeoJSON specification.

Note that any NMaps GL method that accepts a LngLat object as an argument or option can also accept an Array of two numbers and will perform an implicit conversion. This flexible type is documented as LngLatLike.

new LngLat(lng: number, lat: number)

Parameters

lng(number)Longitude, measured in degrees.

lat(number)Latitude, measured in degrees.

Example

const ll = new nmapsgl.LngLat(-123.9749, 40.7736);
ll.lng; // = -123.9749

Static Members

Instance Members

LngLatLike

A LngLat object, an array of two numbers representing longitude and latitude, or an object with lng and lat or lon and lat properties.

Example

const v1 = new nmapsgl.LngLat(-122.420679, 37.772537);
const v2 = [-122.420679, 37.772537];
const v3 = {lon: -122.420679, lat: 37.772537};

LngLatBounds

A LngLatBounds object represents a geographical bounding box, defined by its southwest and northeast points in longitude and latitude.

If no arguments are provided to the constructor, a null bounding box is created.

Note that any NMaps GL method that accepts a LngLatBounds object as an argument or option can also accept an Array of two LngLatLike constructs and will perform an implicit conversion. This flexible type is documented as LngLatBoundsLike.

new LngLatBounds(sw: LngLatLike?, ne: LngLatLike?)

Parameters

sw(LngLatLike?)The southwest corner of the bounding box.

ne(LngLatLike?)The northeast corner of the bounding box.

Example

const sw = new nmapsgl.LngLat(-73.9876, 40.7661);
const ne = new nmapsgl.LngLat(-73.9397, 40.8002);
const llb = new nmapsgl.LngLatBounds(sw, ne);

Static Members

Instance Members

Search Instance Members

LngLatBoundsLike

A LngLatBounds object, an array of LngLatLike objects in [sw, ne] order, or an array of numbers in [west, south, east, north] order.

Example

const v1 = new nmapsgl.LngLatBounds(
new nmapsgl.LngLat(-73.9876, 40.7661),
new nmapsgl.LngLat(-73.9397, 40.8002)
);
const v2 = new nmapsgl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002])
const v3 = [[-73.9876, 40.7661], [-73.9397, 40.8002]];

Point

A Point geometry object, which has x and y properties representing screen coordinates in pixels.

Example

const point = new nmapsgl.Point(-77, 38);

PointLike

A Point or an array of two numbers representing x and y screen coordinates in pixels.

Example

const p1 = new nmapsgl.Point(-77, 38); // a PointLike which is a Point
const p2 = [-77, 38]; // a PointLike which is an array of two numbers

MercatorCoordinate

A MercatorCoordinate object represents a projected three dimensional position.

MercatorCoordinate uses the web mercator projection (EPSG:3857) with slightly different units:

the size of 1 unit is the width of the projected world instead of the "mercator meter"
the origin of the coordinate space is at the north-west corner instead of the middle

For example, MercatorCoordinate(0, 0, 0) is the north-west corner of the mercator world and MercatorCoordinate(1, 1, 0) is the south-east corner. If you are familiar with vector tiles it may be helpful to think of the coordinate space as the 0/0/0 tile with an extent of 1.

The z dimension of MercatorCoordinate is conformal. A cube in the mercator coordinate space would be rendered as a cube.

new MercatorCoordinate(x: number, y: number, z: number)

Parameters

x(number)The x component of the position.

y(number)The y component of the position.

z(number)(default 0)The z component of the position.

Example

const nullIsland = new nmapsgl.MercatorCoordinate(0.5, 0.5, 0);

Static Members

Instance Members

Add a custom style layer

EdgeInsets

An EdgeInset object represents screen space padding applied to the edges of the viewport. This shifts the apprent center or the vanishing point of the map. This is useful for adding floating UI elements on top of the map and having the vanishing point shift as UI elements resize.

new EdgeInsets(top: number, bottom: number, left: number, right: number)

Parameters

top(number)(default 0)

bottom(number)(default 0)

left(number)(default 0)

right(number)(default 0)

addControl

addImage

addLayer

addSource

areTilesLoaded

boxZoom

cameraForBounds

doubleClickZoom

dragPan

dragRotate

easeTo

fitBounds

fitScreenCoordinates

flyTo

getBearing

getBounds

getCanvas

getCanvasContainer

getCenter

getContainer

getFeatureState

getFilter

getLayer

getLayoutProperty

getLight

getMaxBounds

getMaxPitch

getMaxZoom

getMinPitch

getMinZoom

getPadding

getPaintProperty

getPitch

getRenderWorldCopies

getSource

getStyle

getZoom

hasControl

hasImage

isMoving

isRotating

isSourceLoaded

isStyleLoaded

isZooming

jumpTo

keyboard

listImages

loaded

loadImage

moveLayer

off

off

on

once

once

panBy

panTo

project

queryRenderedFeatures

querySourceFeatures

remove

removeControl

removeFeatureState

removeImage

removeLayer

removeSource

repaint

resetNorth

resetNorthPitch

resize

rotateTo

scrollZoom

setBearing

setCenter

setFeatureState

setFilter

setLayerZoomRange

setLayoutProperty

setLight