Mapbox GL JS

Adds a Control to the map, calling control.addTo(this).

Adds a Mapbox style class to the map.

Keep in mind that these classes are used for controlling a style layer's paint properties, so are not reflected in an HTML element's class attribute. To learn more about Mapbox style classes, read about Layers in the style specification.

Removes a Mapbox style class from the map.

Replaces the map's existing Mapbox style classes with a new array of classes.

Returns a Boolean indicating whether the map has the specified Mapbox style class.

Returns the map's Mapbox style classes.

Resizes the map according to the dimensions of its container element.

This method must be called after the map's container is resized by another script, or when the map is shown after being initially hidden with CSS.

Returns the map's geographical bounds.

Sets or clears the map's geographical bounds.

Pan and zoom operations are constrained within these bounds. If a pan or zoom is performed that would display regions outside these bounds, the map will instead display a position and zoom level as close as possible to the operation's request while still remaining within the bounds.

Sets or clears the map's minimum zoom level. If the map's current zoom level is lower than the new minimum, the map will zoom to the new minimum.

Sets or clears the map's maximum zoom level. If the map's current zoom level is higher than the new maximum, the map will zoom to the new maximum.

Returns a Point representing pixel coordinates, relative to the map's container, that correspond to the specified geographical location.

Returns a LngLat representing geographical coordinates that correspond to the specified pixel coordinates.

Returns an array of GeoJSON Feature objects representing visible features that satisfy the query parameters.

The properties value of each returned feature object contains the properties of its source feature. For GeoJSON sources, only string and numeric property values are supported (i.e. null, Array, and Object values are not supported).

Each feature includes a top-level layer property whose value is an object representing the style layer to which the feature belongs. Layout and paint properties in this object contain values which are fully evaluated for the given zoom level and feature.

Only visible features are returned. The topmost rendered feature appears first in the returned array, and subsequent features are sorted by descending z-order. Features that are rendered multiple times (due to wrapping across the antimeridian at low zoom levels) are returned only once (though subject to the following caveat).

Because features come from tiled vector data or GeoJSON data that is converted to tiles internally, feature geometries are clipped at tile boundaries and, as a result, features may appear multiple times in query results when they span multiple tiles. For example, suppose there is a highway running through the bounding rectangle of a query. The results of the query will be those parts of the highway that lie within the map tiles covering the bounding rectangle, even if the highway extends into other tiles, and the portion of the highway within each map tile will be returned as a separate feature.

// Find all features at a point
var features = map.queryRenderedFeatures(
  [20, 35],
  { layers: ['my-layer-name'] }
);

// Find all features within a static bounding box
var features = map.queryRenderedFeatures(
  [[10, 20], [30, 50]],
  { layers: ['my-layer-name'] }
);

// Find all features within a bounding box around a point
var width = 10;
var height = 20;
var features = map.queryRenderedFeatures([
  [point.x - width / 2, point.y - height / 2],
  [point.x + width / 2, point.y + height / 2]
], { layers: ['my-layer-name'] });

// Query all rendered features from a single layer
var features = map.queryRenderedFeatures({ layers: ['my-layer-name'] });

Returns an array of GeoJSON Feature objects representing features within the specified vector tile or GeoJSON source that satisfy the query parameters.

In contrast to Map#queryRenderedFeatures, this function returns all features matching the query parameters, whether or not they are rendered by the current style (i.e. visible). The domain of the query includes all currently-loaded vector tiles and GeoJSON source tiles: this function does not check tiles outside the currently visible viewport.

Because features come from tiled vector data or GeoJSON data that is converted to tiles internally, feature geometries are clipped at tile boundaries and, as a result, features may appear multiple times in query results when they span multiple tiles. For example, suppose there is a highway running through the bounding rectangle of a query. The results of the query will be those parts of the highway that lie within the map tiles covering the bounding rectangle, even if the highway extends into other tiles, and the portion of the highway within each map tile will be returned as a separate feature.

Replaces the map's Mapbox style object with a new value.

Returns the map's Mapbox style object, which can be used to recreate the map's style.

Adds a source to the map's style.

Removes a source from the map's style.

Returns the source with the specified ID in the map's style.

Adds a Mapbox style layer to the map's style.

A layer defines styling for data from a specified source.

Removes a layer from the map's style.

Also removes any layers which refer to the specified layer via a ref property.

• Error: if no layer with the specified id exists.

Returns the layer with the specified ID in the map's style.

Sets the filter for the specified style layer.

map.setFilter('my-layer', ['==', 'name', 'USA']);

Sets the zoom extent for the specified style layer.

map.setLayerZoomRange('my-layer', 2, 5);

Returns the filter applied to the specified style layer.

Sets the value of a paint property in the specified style layer.

map.setPaintProperty('my-layer', 'fill-color', '#faafee');

Returns the value of a paint property in the specified style layer.

Sets the value of a layout property in the specified style layer.

map.setLayoutProperty('my-layer', 'visibility', 'none');

Returns the value of a layout property in the specified style layer.

Returns the map's containing HTML element.

Returns the HTML element containing the map's <canvas> element.

If you want to add non-GL overlays to the map, you should append them to this element.

This is the element to which event bindings for map interactivity (such as panning and zooming) are attached. It will receive bubbled events from child elements such as the <canvas>, but not from map controls.

Returns the map's <canvas> element.

Returns a Boolean indicating whether the map is fully loaded.

Returns false if the style is not yet fully loaded, or if there has been a change to the sources or style that has not yet fully loaded.

Destroys the map's underlying resources, including web workers and DOM elements.

After calling this method, you must not call any other methods on the map.

Gets and sets a Boolean indicating whether the map will render an outline around each tile. These tile boundaries are useful for debugging.

Gets and sets a Boolean indicating whether the map will render boxes around all symbols in the data source, revealing which symbols were rendered or which were hidden due to collisions. This information is useful for debugging.

Gets and sets a Boolean indicating whether the map will continuously repaint. This information is useful for analyzing performance.

Returns the map's geographical centerpoint.

Sets the map's geographical centerpoint. Equivalent to jumpTo({center: center}).

map.setCenter([-74, 38]);

Pans the map by the specified offest.

Pans the map to the specified location, with an animated transition.

Returns the map's current zoom level.

Sets the map's zoom level. Equivalent to jumpTo({zoom: zoom}).

// zoom the map to 5
map.setZoom(5);

Zooms the map to the specified zoom level, with an animated transition.

Increases the map's zoom level by 1.

Decreases the map's zoom level by 1.

Returns the map's current bearing (rotation).

Sets the maps' bearing (rotation). Equivalent to jumpTo({bearing: bearing}).

// rotate the map to 90 degrees
map.setBearing(90);

Rotates the map to the specified bearing, with an animated transition.

Rotates the map to a bearing of 0 (due north), with an animated transition.

Snaps the map's bearing to 0 (due north), if the current bearing is close enough to it (i.e. within the bearingSnap threshold).

Returns the map's current pitch (tilt).

Sets the map's pitch (tilt). Equivalent to jumpTo({pitch: pitch}).

Pans and zooms the map to contain its visible area within the specified geographical bounds.

Changes any combination of center, zoom, bearing, and pitch, without an animated transition. The map will retain its current values for any details not specified in options.

Changes any combination of center, zoom, bearing, and pitch, with an animated transition between old and new values. The map will retain its current values for any details not specified in options.

Changes any combination of center, zoom, bearing, and pitch, animating the transition along a curve that evokes flight. The animation seamlessly incorporates zooming and panning to help the user maintain her bearings even after traversing a great distance.

// fly with default options to null island
map.flyTo({center: [0, 0], zoom: 9});
// using flyTo options
map.flyTo({
  center: [0, 0],
  zoom: 9,
  speed: 0.2,
  curve: 1,
  easing: function(t) {
    return t;
  }
});

Stops any animated transition underway.

Fired when the WebGL context is lost.

Fired when the WebGL context is restored.

Fired when a touch point has been disrupted.

Fired whenever the map is drawn to the screen, as the result of

• a change to the map's position, zoom, pitch, or bearing
• a change to the map's style
• a change to a GeoJSON source
• the loading of a vector tile, GeoJSON file, glyph, or sprite

Fired if any error occurs. This is GL JS's primary error reporting mechanism. We use an event instead of throw to better accommodate asyncronous operations. If no listeners are bound to the error event, the error will be printed to the console.

Fired just after the map completes a transition from one view to another, as the result of either user interaction or methods such as Map#jumpTo.

Fired when a pointing device (usually a mouse) is pressed within the map.

Fired when a pointing device (usually a mouse) is released within the map.

Fired when a pointing device (usually a mouse) is moved within the map.

Fired when a touch point is placed on the map.

Fired when a touch point is removed from the map.

Fired when a touch point is moved within the map.

Fired when a point device (usually a mouse) leaves the map's canvas.

Fired when a pointing device (usually a mouse) is pressed and released at the same point on the map.

Fired when a pointing device (usually a mouse) is clicked twice at the same point on the map.

Fired when the right button of the mouse is clicked or the context menu key is pressed within the map.

Fired immediately after all necessary resources have been downloaded and the first visually complete rendering of the map has occurred.

Fired just before the map begins a transition from one view to another, as the result of either user interaction or methods such as Map#jumpTo.

Fired repeatedly during an animated transition from one view to another, as the result of either user interaction or methods such as Map#flyTo.

Fired just after the map completes a transition from one zoom level to another, as the result of either user interaction or methods such as Map#flyTo.

Fired repeatedly during an animated transition from one zoom level to another, as the result of either user interaction or methods such as Map#flyTo.

Fired just before the map begins a transition from one zoom level to another, as the result of either user interaction or methods such as Map#flyTo.

Fired when a "box zoom" interaction ends. See BoxZoomHandler.

Fired when the user cancels a "box zoom" interaction, or when the bounding box does not meet the minimum size threshold. See BoxZoomHandler.

Fired when a "box zoom" interaction starts. See BoxZoomHandler.

Fired repeatedly during a "drag to rotate" interaction. See DragRotateHandler.

Fired when a "drag to rotate" interaction starts. See DragRotateHandler.

Fired when a "drag to rotate" interaction ends. See DragRotateHandler.

Fired when a "drag to pan" interaction ends. See DragPanHandler.

Fired when a "drag to pan" interaction starts. See DragPanHandler.

Fired repeatedly during a "drag to pan" interaction. See DragPanHandler.

Fired whenever the map's pitch (tilt) changes.

Converts an array of two numbers to a LngLat object.

If a LngLat object is passed in, the function returns it unchanged.

var arr = [-73.9749, 40.7736];
var ll = mapboxgl.LngLat.convert(arr);
ll;   // = LngLat {lng: -73.9749, lat: 40.7736}

Returns a new LngLat object whose longitude is wrapped to the range (-180, 180).

var ll = new mapboxgl.LngLat(286.0251, 40.7736);
var wrapped = ll.wrap();
wrapped.lng; // = -73.9749

Returns the coordinates represented as an array of two numbers.

var ll = new mapboxgl.LngLat(-73.9749, 40.7736);
ll.toArray(); // = [-73.9749, 40.7736]

Returns the coordinates represent as a string.

var ll = new mapboxgl.LngLat(-73.9749, 40.7736);
ll.toString(); // = "LngLat(-73.9749, 40.7736)"

Converts an array to a LngLatBounds object.

If a LngLatBounds object is passed in, the function returns it unchanged.

Internally, the function calls LngLat#convert to convert arrays to LngLat values.

var arr = [[-73.9876, 40.7661], [-73.9397, 40.8002]];
var llb = mapboxgl.LngLatBounds.convert(arr);
llb;   // = LngLatBounds {_sw: LngLat {lng: -73.9876, lat: 40.7661}, _ne: LngLat {lng: -73.9397, lat: 40.8002}}

Extends the bounding box to include an area represented by a LngLat or LngLatBounds.

Returns the geographical coordinate equidistant from the bounding box's corners.

var llb = new mapboxgl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
llb.getCenter(); // = LngLat {lng: -73.96365, lat: 40.78315}

Returns the southwest corner of the bounding box.

Returns the northeast corner of the bounding box.

Returns the northwest corner of the bounding box.

Returns the southeast corner of the bounding box.

Returns the west edge of the bounding box.

Returns the south edge of the bounding box.

Returns the east edge of the bounding box.

Returns the north edge of the bounding box.

Returns the bounding box represented as an array.

var llb = new mapboxgl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
llb.toArray(); // = [[-73.9876, 40.7661], [-73.9397, 40.8002]]

Return the bounding box represented as a string.

var llb = new mapboxgl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
llb.toString(); // = "LngLatBounds(LngLat(-73.9876, 40.7661), LngLat(-73.9397, 40.8002))"

error event.

geolocate event.

Adds the control to a map.

Removes the control from the map it has been added to.

Returns a Boolean indicating whether the "box zoom" interaction is enabled.

Returns a Boolean indicating whether the "box zoom" interaction is active, i.e. currently being used.

Enables the "box zoom" interaction.

map.boxZoom.enable();

Disables the "box zoom" interaction.

map.boxZoom.disable();

Returns a Boolean indicating whether the "scroll to zoom" interaction is enabled.

Enables the "scroll to zoom" interaction.

map.scrollZoom.enable();

Disables the "scroll to zoom" interaction.

map.scrollZoom.disable();

Returns a Boolean indicating whether the "drag to pan" interaction is enabled.

Returns a Boolean indicating whether the "drag to pan" interaction is active, i.e. currently being used.

Enables the "drag to pan" interaction.

map.dragPan.enable();

Disables the "drag to pan" interaction.

map.dragPan.disable();

Returns a Boolean indicating whether the "drag to rotate" interaction is enabled.

Returns a Boolean indicating whether the "drag to rotate" interaction is active, i.e. currently being used.

Enables the "drag to rotate" interaction.

map.dragRotate.enable();

Disables the "drag to rotate" interaction.

map.dragRotate.disable();

Returns a Boolean indicating whether keyboard interaction is enabled.

Enables keyboard interaction.

map.keyboard.enable();

Disables keyboard interaction.

map.keyboard.disable();

Returns a Boolean indicating whether the "double click to zoom" interaction is enabled.

Enables the "double click to zoom" interaction.

map.doubleClickZoom.enable();

Disables the "double click to zoom" interaction.

map.doubleClickZoom.disable();

Returns a Boolean indicating whether the "pinch to rotate and zoom" interaction is enabled.

Enables the "pinch to rotate and zoom" interaction.

map.touchZoomRotate.enable();

Disables the "pinch to rotate and zoom" interaction.

map.touchZoomRotate.disable();

Disables the "pinch to rotate" interaction, leaving the "pinch to zoom" interaction enabled.

map.touchZoomRotate.disableRotation();

Enables the "pinch to rotate" interaction.

map.touchZoomRotate.enable();
  map.touchZoomRotate.enableRotation();

Sets the GeoJSON data and re-renders the map.

Returns the HTML video element.

Sets the video's coordinates and re-renders the map.

Sets the image's coordinates and re-renders the map.

Adds the popup to a map.

Removes the popup from the map it has been added to.

var popup = new mapboxgl.Popup().addTo(map);
popup.remove();

Returns the geographical location of the popup's anchor.

Sets the geographical location of the popup's anchor, and moves the popup to it.

Sets the popup's content to a string of text.

This function creates a Text node in the DOM, so it cannot insert raw HTML. Use this method for security against XSS if the popup content is user-provided.

var popup = new mapboxgl.Popup()
  .setLngLat(e.lngLat)
  .setText('Hello, world!')
  .addTo(map);

Sets the popup's content to the HTML provided as a string.

Sets the popup's content to the element provided as a DOM node.

// create an element with the popup content
var div = document.createElement('div');
div.innerHTML = 'Hello, world!';
var popup = new mapboxgl.Popup()
  .setLngLat(e.lngLat)
  .setDOMContent(div)
  .addTo(map);

Fired when the popup is closed manually or programatically.

Attaches the marker to a map

Removes the marker from a map

var marker = new mapboxgl.Marker().addTo(map);
marker.remove();

Get the marker's geographical location

Set the marker's geographical position and move it.

Adds a listener to a specified event type.

Removes a previously registered event listener.

Adds a listener that will be called only once to a specified event type.

The listener will be called first time the event fires after the listener is registered.

Fires an event of the specified type.

Returns a Boolean indicating whether any listeners are registered for a specified event type.