Mapbox GL JS

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

Adds a style class to a map.

Removes a style class from a map.

Helper method to add more than one class.

Check whether a style class is active.

Return an array of the current active style classes.

Detect the map's new width and height and resize it. Given the container of the map specified in the Map constructor, this reads the new width from the DOM: so this method is often called after the map's container is resized by another script or the map is shown after being initially hidden with CSS.

Get the map's geographical bounds.

Set constraint on the map's geographical bounds. Pan or zoom operations that would result in displaying regions that fall outside of the bounds instead result in displaying the map at the closest point and/or zoom level of the requested operation that is within the max bounds.

Set the map's minimum zoom level, and zooms map to that level if it is currently below it. If no parameter provided, unsets the current minimum zoom (sets it to 0)

Set the map's maximum zoom level, and zooms map to that level if it is currently above it. If no parameter provided, unsets the current maximum zoom (sets it to 20)

Get pixel coordinates relative to the map container, given a geographical location.

Get geographical coordinates, given pixel coordinates.

Query rendered features within a point or rectangle.

var features = map.queryRenderedFeatures([20, 35], { layers: ['my-layer-name'] });

var features = map.queryRenderedFeatures([[10, 20], [30, 50]], { layers: ['my-layer-name'] });

Get data from vector tiles as an array of GeoJSON Features.

Replaces the map's style object with a new value. Unlike the style option in the Map constructor, this method only accepts an object of a new style, not a URL string.

Get a style object that can be used to recreate the map's style.

Add a source to the map style.

Remove an existing source from the map style.

Return the style source object with the given id.

Add a layer to the map style. The layer will be inserted before the layer with ID before, or appended if before is omitted.

Remove the layer with the given id from the map. Any layers which refer to the specified layer via a ref property are also removed.

• Error: if no layer with the given id exists

Return the style layer object with the given id.

Set the filter for a given style layer.

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

Set the zoom extent for a given style layer.

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

Get the filter for a given style layer.

Set the value of a paint property in a given style layer.

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

Get the value of a paint property in a given style layer.

Set the value of a layout property in a given style layer.

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

Get the value of a layout property in a given style layer.

Get the Map's container as an HTML element

Get the container for the map 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 for child elements such as the canvas, but not for map controls.

Get the Map's canvas as an HTML canvas

Is this map fully loaded? If the style isn't loaded or it has a change to the sources or style that isn't propagated to its style, return false.

Destroys the map's underlying resources, including web workers and DOM elements. Afterwards, you must not call any further methods on this Map instance.

A default error handler for style.error, source.error, layer.error, and tile.error events. It logs the error via console.error.

// Disable the default error handler
map.off('style.error', map.onError);
map.off('source.error', map.onError);
map.off('tile.error', map.onError);
map.off('layer.error', map.onError);

Draw an outline around each rendered tile for debugging.

Draw boxes around all symbols in the data source, showing which were rendered and which were hidden due to collisions with other symbols for style debugging.

Enable continuous repaint to analyze performance.

Get the current view geographical point.

Sets a map location. Equivalent to jumpTo({center: center}).

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

Pan by a certain number of pixels

Pan to a certain location with easing

Get the current zoom

Sets a map zoom. Equivalent to jumpTo({zoom: zoom}).

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

Zooms to a certain zoom level with easing.

Zoom in by 1 level

Zoom out by 1 level

Get the current bearing in degrees

Sets a map rotation. Equivalent to jumpTo({bearing: bearing}).

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

Rotate bearing by a certain number of degrees with easing

Sets map bearing to 0 (north) with easing

Animates map bearing to 0 (north) if it's already close to it.

Get the current angle in degrees

Sets a map angle. Equivalent to jumpTo({pitch: pitch}).

Zoom to contain certain geographical bounds

Change any combination of center, zoom, bearing, and pitch, without a transition. The map will retain the current values for any options not included in options.

Change any combination of center, zoom, bearing, and pitch, with a smooth animation between old and new values. The map will retain the current values for any options not included in options.

Change any combination of center, zoom, bearing, and pitch, animated along a curve that evokes flight. The transition animation seamlessly incorporates zooming and panning to help the user find his or 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;
  }
});

Stop current animation

WebGL Context Lost event.

WebGL Context Restored event.

This event is fired whenever the map is drawn to the screen because of

• a change in map position, zoom, pitch, or bearing
• a change to the map style
• a change to a GeoJSON source
• a vector tile, GeoJSON file, glyph, or sprite being loaded

Context menu event.

Double click event.

Click event.

Touch cancel event.

Touch move event.

Touch end event.

Touch start event.

Mouse move event.

Mouse up event.

Mouse down event.

Move end event. This event is emitted just after the map completes a transition from one view to another, either as a result of user interaction or the use of methods such as Map#jumpTo.

Move event. This event is emitted repeatedly during animated transitions from one view to another, either as a result of user interaction or the use of methods such as Map#jumpTo.

Move start event. This event is emitted just before the map begins a transition from one view to another, either as a result of user interaction or the use of methods such as Map#jumpTo.

Load event. This event is emitted immediately after all necessary resources have been downloaded and the first visually complete rendering has occurred.

Zoom event. This event is emitted repeatedly during animated transitions from one zoom level to another, either as a result of user interaction or the use of methods such as Map#jumpTo.

Zoom start event. This event is emitted just before the map begins a transition from one zoom level to another, either as a result of user interaction or the use of methods such as Map#jumpTo.

Zoom end event. This event is emitted just after the map completes a transition from one zoom level to another, either as a result of user interaction or the use of methods such as Map#jumpTo.

Boxzoom start event. This event is emitted at the start of a box zoom interaction.

Boxzoom end event. This event is emitted at the end of a box zoom interaction

Boxzoom cancel event. This event is emitted when the user cancels a box zoom interaction, or when the box zoom does not meet the minimum size threshold.

Rotate end event. This event is emitted at the end of a user-initiated rotate interaction.

Rotate event. This event is emitted repeatedly during a user-initiated rotate interaction.

Rotate start event. This event is emitted at the start of a user-initiated rotate interaction.

Drag event. This event is emitted repeatedly during a user-initiated pan interaction.

Drag end event. This event is emitted at the end of a user-initiated pan interaction.

Drag start event. This event is emitted at the start of a user-initiated pan interaction.

Pitch event. This event is emitted whenever the map's pitch changes.

Convert an array to a LngLat object, or return an existing LngLat object unchanged.

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

Return 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

Return a LngLat as an array

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

Return a LngLat as a string

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

Convert an array to a LngLatBounds object, or return an existing LngLatBounds object unchanged.

Calls LngLat#convert internally to convert arrays as 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}}

Extend the bounds to include a given LngLat or LngLatBounds.

Get the point equidistant from this 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}

Get southwest corner

Get northeast corner

Get northwest corner

Get southeast corner

Get west edge longitude

Get south edge latitude

Get east edge longitude

Get north edge latitude

Return a LngLatBounds 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 a LngLatBounds 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))"

Add this control to the map, returning the control itself for chaining. This will insert the control's DOM element into the map's DOM element if the control has a position specified.

Remove this control from the map it has been added to.

Returns the current enabled/disabled state of the "box zoom" interaction.

Returns true if the "box zoom" interaction is currently active, i.e. currently being used.

Enable the "box zoom" interaction.

map.boxZoom.enable();

Disable the "box zoom" interaction.

map.boxZoom.disable();

Returns the current enabled/disabled state of the "scroll to zoom" interaction.

Enable the "scroll to zoom" interaction.

map.scrollZoom.enable();

Disable the "scroll to zoom" interaction.

map.scrollZoom.disable();

Returns the current enabled/disabled state of the "drag to pan" interaction.

Returns true if the "drag to pan" interaction is currently active, i.e. currently being used.

Enable the "drag to pan" interaction.

map.dragPan.enable();

Disable the "drag to pan" interaction.

map.dragPan.disable();

Returns the current enabled/disabled state of the "drag to rotate" interaction.

Returns true if the "drag to rotate" interaction is currently active, i.e. currently being used.

Enable the "drag to rotate" interaction.

map.dragRotate.enable();

Disable the "drag to rotate" interaction.

map.dragRotate.disable();

Returns the current enabled/disabled state of keyboard interaction.

Enable the ability to interact with the map using keyboard input.

map.keyboard.enable();

Disable the ability to interact with the map using keyboard input.

map.keyboard.disable();

Returns the current enabled/disabled state of the "double click to zoom" interaction.

Enable the "double click to zoom" interaction.

map.doubleClickZoom.enable();

Disable the "double click to zoom" interaction.

map.doubleClickZoom.disable();

Returns the current enabled/disabled state of the "pinch to rotate and zoom" interaction.

Enable the "pinch to rotate and zoom" interaction.

map.touchZoomRotate.enable();

Disable the "pinch to rotate and zoom" interaction.

map.touchZoomRotate.disable();

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

map.touchZoomRotate.disableRotation();

Enable the "pinch to rotate" interaction, undoing a call to disableRotation.

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

Update source geojson data and rerender map

Return the HTML video element.

Update video coordinates and rerender map

Update image coordinates and rerender map

Attaches the popup to a map

Removes the popup from a map

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

Get the popup's geographical location

Set the popup's geographical position and move it.

Fill a popup element with text only content. This creates a text node in the DOM, so it cannot end up appending raw HTML. Use this method if you want an added level of security against XSS if the popup content is user-provided.

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

Fill a popup element with HTML content, provided as a string.

Fill a popup element with DOM content

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

Subscribe to a specified event with a listener function the latter gets the data object that was passed to fire and additionally target and type properties

Remove a event listener

Call a function once when an event has fired

Fire event of a given string type with the given data object

Check if an event is registered to a type