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.

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.

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

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

Adds a source to the map's style.

• Draw GeoJSON points

• Style circles using data-driven styling

• Set a point after Geocoder result

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

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 a layer from the map's style.

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

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 under the mouse pointer

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

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

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

• 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

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#remove.

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

• Highlight features within a bounding box

• Create a draggable 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 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 one of the map's sources' tiles begins loading or changing asyncronously. All tiledataloading events are followed by a tiledata or error event. See MapDataEvent for more information.

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 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 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 begins loading or changing asyncronously. This event is not fired if a tile belonging to a source begins loading or changing (that is handled by tiledataloading). 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 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 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 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 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 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 when any map data loads or changes. See MapDataEvent for more information.

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

Fired when one of the map's sources loads or changes. This event is not fired if a tile belonging to a source loads or changes (that is handled by tiledata). 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 one of the map's sources' tiles loads or changes. See MapDataEvent for more information.

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.

• Update a choropleth layer by zoom level

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 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 ends. 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 ends. See DragPanHandler.

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

Fired when a "drag to pan" interaction starts. 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}}

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

geolocate event.

error event.

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

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

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.

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.

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.

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.