Mapbox GL JS

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

• Display map navigation controls

Removes the control from the map.

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.

Note: Style classes are deprecated and will be removed in an upcoming release of Mapbox GL JS.

Removes a Mapbox style class from the map.

Note: Style classes are deprecated and will be removed in an upcoming release of Mapbox GL JS.

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

Note: Style classes are deprecated and will be removed in an upcoming release of Mapbox GL JS.

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

Note: Style classes are deprecated and will be removed in an upcoming release of Mapbox GL JS.

Returns the map's Mapbox style classes.

Note: Style classes are deprecated and will be removed in an upcoming release of Mapbox GL JS.

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.

Gets the map's geographical bounds.

Returns the LngLatBounds by which pan and zoom operations on the map are constrained.

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.

Returns the map's minimum allowable zoom level.

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 the map's maximum allowable zoom level.

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.

• Show polygon information on click

Adds a listener for events of a specified type.

Adds a listener for events of a specified type occurring on features in a specified style layer.

Removes an event listener previously added with Map#on.

Removes an event listener for layer-specific events previously added with Map#on.

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.

Features from layers whose visibility property is "none", or from layers whose zoom range excludes the current zoom level are not included. Symbol features that have been hidden due to text or icon collision are not included. Features from all other layers are included, including features that may have no visible contribution to the rendered result; for example, because the layer's opacity or color alpha component is set to 0.

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 may be split or duplicated across tile boundaries and, as a result, features may appear multiple times in query results. 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. Similarly, a point feature near a tile boundary may appear in multiple tiles due to tile buffering.

// 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'] });

• Get features under the mouse pointer

• Highlight features within a bounding box

• Center the map on a clicked symbol

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 may be split or duplicated across tile boundaries and, as a result, features may appear multiple times in query results. 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. Similarly, a point feature near a tile boundary may appear in multiple tiles due to tile buffering.

• Filter features within map view

• Highlight features containing similar data

Updates the map's Mapbox style object with a new value. If the given value is style JSON object, compares it against the the map's current state and perform only the changes necessary to make the map style match the desired state.

• Change a map's style

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

Returns a Boolean indicating whether the map's style is fully loaded.

Adds a source to the map's style.

• Draw GeoJSON points

• Style circles using data-driven styling

• Set a point after Geocoder result

Returns a Boolean indicating whether the source is loaded.

Returns a Boolean indicating whether all tiles in the viewport from all sources on the style are loaded.

Removes a source from the map's style.

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

• Create a draggable point

• Animate a point

• Add live realtime data

Add an image to the style. This image can be used in icon-image, background-pattern, fill-pattern, and line-pattern. An Map#error event will be fired if there is not enough space in the sprite to add this image.

• Add an icon to the map

• Add a generated icon to the map

Remove an image from the style (such as one used by icon-image or background-pattern).

Load an image from an external URL for use with Map#addImage. External domains must support CORS.

• Add an icon to the map

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

A layer defines styling for data from a specified source.

• Create and style clusters

• Add a vector tile source

• Add a WMS source

Moves a layer to a different z-position.

Removes the layer with the given id from the map's style.

If no such layer exists, an error event is fired.

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

• Filter symbols by toggling a list

• Filter symbols by text input

Sets the filter for the specified style layer.

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

• Filter features within map view

• Highlight features containing similar data

• Create a timeline animation

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');

• Change a layer's color with buttons

• Adjust a layer's opacity

• Create a draggable point

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.

Sets the any combination of light values.

Returns the value of the light object.

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.

• Create a draggable point

• Highlight features within a bounding box

Returns the map's <canvas> element.

• Measure distances

• Display a popup on hover

• Center the map on a clicked symbol

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.

Clean up and release all internal resources associated with this map.

This includes DOM elements, event bindings, web workers, and WebGL resources.

Use this method when you are done using the map and wish to ensure that it no longer consumes browser resources. Afterwards, 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]);

• Move symbol with the keyboard

Pans the map by the specified offest.

• Navigate the map with game-like controls

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

• Navigate the map with game-like controls

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. This function will also reset the map's bearing to 0 if bearing is nonzero.

var bbox = [[-79, 43], [-73, 45]];
map.fitBounds(bbox, {
  padding: {top: 10, bottom:25, left: 15, right: 5}
});

• Fit a map to a bounding box

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.

• Navigate the map with game-like controls

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(t) {
    return t;
  }
});

• Fly to a location

• Slowly fly to a location

• Fly to a location based on scroll position

Returns a Boolean indicating whether the camera is moving.

Stops any animated transition underway.

Fired immediately after the map has been resized.

Fired when the WebGL context is lost.

Fired when the WebGL context is restored.

Fired immediately after the map has been removed with Map.event:remove.

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

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

• Measure distances

• Center the map on a clicked symbol

Fired when a touch point has been disrupted.

Fired when a touch point is moved within the map.

Fired when a touch point is removed from the map.

Fired when a touch point is placed on the map.

Fired when one of the map's sources loads or changes, including if a tile belonging to a source loads or changes. See MapDataEvent for more information.

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

• Get coordinates of the mouse pointer

• Highlight features under the mouse pointer

• Display a popup on hover

Fired when the map's style loads or changes. See MapDataEvent for more information.

Fired when any map data loads or changes. See MapDataEvent for more information.

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

• Highlight features under the mouse pointer

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 when an 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.

• Play map locations as a slideshow

• Filter features within map view

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 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 immediately after all necessary resources have been downloaded and the first visually complete rendering of the map has occurred.

• Draw GeoJSON points

• Add live realtime data

• Animate a point

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

• Highlight features within a bounding box

• Create a draggable point

Fired when one of the map's sources begins loading or changing asyncronously. All sourcedataloading events are followed by a sourcedata or error event. See MapDataEvent for more information.

Fired when the map's style begins loading or changing asyncronously. All styledataloading events are followed by a styledata or error event. See MapDataEvent for more information.

Fired when any map data (style, source, tile, etc) begins loading or changing asyncronously. All dataloading events are followed by a data or error event. See MapDataEvent for more information.

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

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

• Highlight features within a bounding box

• Create a draggable point

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.

• Update a choropleth layer by zoom level

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 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 starts. See BoxZoomHandler.

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 "drag to rotate" interaction starts. See DragRotateHandler.

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

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

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

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

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

Fired whenever the map's pitch (tilt) begins a change as the result of either user interaction or methods such as Map#flyTo .

Fired whenever the map's pitch (tilt) changes as. the result of either user interaction or methods such as Map#flyTo.

Fired immediately after the map's pitch (tilt) finishes changing as the result of either user interaction or methods such as Map#flyTo.

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)"

Returns a LngLatBounds from the coordinates extended by a given radius.

var ll = new mapboxgl.LngLat(-73.9749, 40.7736);
ll.toBounds(100).toArray(); // = [[-73.97501862141328, 40.77351016847229], [-73.97478137858673, 40.77368983152771]]

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}}

Set the northeast corner of the bounding box

Set the southwest corner of the bounding box

Extend the bounds to include a given 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))"

Optionally provide a default position for this control. If this method is implemented and Map#addControl is called without the position parameter, the value returned by getDefaultPosition will be used as the control's position.

Register a control on the map and give it a chance to register event listeners and resources. This method is called by Map#addControl internally.

Unregister a control on the map and give it a chance to detach event listeners and resources. This method is called by Map#removeControl internally.

Fired on each Geolocation API position update which returned as success.

Fired when the Geolocate Control changes to the active lock state, which happens either upon first obtaining a successful Geolocation API position for the user (a geolocate event will follow), or the user clicks the geolocate button when in the background state which uses the last known position to recenter the map and enter active lock state (no geolocate event will follow unless the users's location changes).

Fired when the Geolocate Control changes to the background state, which happens when a user changes the camera during an active position lock. This only applies when trackUserLocation is true. In the background state, the dot on the map will update with location updates but the camera will not.

Fired on each Geolocation API position update which returned as an error.

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.

The longitude of the result may differ by a multiple of 360 degrees from the longitude previously set by setLngLat because Popup wraps the anchor longitude across copies of the world to keep the popup on screen.

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.

This method does not perform HTML filtering or sanitization, and must be used only with trusted content. Consider Popup#setText if the content is an untrusted text string.

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

// create an element with the popup content
var div = window.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.

The longitude of the result may differ by a multiple of 360 degrees from the longitude previously set by setLngLat because Marker wraps the anchor longitude across copies of the world to keep the marker on screen.

Set the marker's geographical position and move it.

Binds a Popup to the Marker

Returns the Popup instance that is bound to the Marker

Opens or closes the bound popup, depending on the current state

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();

map.scrollZoom.enable({ around: 'center' })

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();

map.touchZoomRotate.enable({ around: 'center' });

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.

Returns the HTML canvas element.

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

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 true if this instance of Evented or any forwardeed instances of Evented have a listener for the specified type.