JavaScript Style Specification iOS Android

Table of Contents

VideoSource

Extends ImageSource

A data source containing video. (See the Style Specification for detailed documentation of options.)

Parameters

  • id string
  • options VideoSourceSpecification
  • dispatcher Dispatcher
  • eventedParent Evented

Examples

// add to map
map.addSource('some id', {
   type: 'video',
   url: [
       'https://www.mapbox.com/blog/assets/baltimore-smoke.mp4',
       'https://www.mapbox.com/blog/assets/baltimore-smoke.webm'
   ],
   coordinates: [
       [-76.54, 39.18],
       [-76.52, 39.18],
       [-76.52, 39.17],
       [-76.54, 39.17]
   ]
});

// update
var mySource = map.getSource('some id');
mySource.setCoordinates([
    [-76.54335737228394, 39.18579907229748],
    [-76.52803659439087, 39.1838364847587],
    [-76.5295386314392, 39.17683392507606],
    [-76.54520273208618, 39.17876344106642]
]);

map.removeSource('some id');  // remove

pause

Pauses the video.

play

Plays the video.

getVideo

Returns the HTML video element.

Returns HTMLVideoElement The HTML video element.

setCoordinates

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

Returns VideoSource this

ImageSource

Extends Evented

A data source containing an image. (See the Style Specification for detailed documentation of options.)

Parameters

  • id string
  • options **(ImageSourceSpecification VideoSourceSpecification CanvasSourceSpecification)**
  • dispatcher Dispatcher
  • eventedParent Evented

Examples

// add to map
map.addSource('some id', {
   type: 'image',
   url: 'https://www.mapbox.com/images/foo.png',
   coordinates: [
       [-76.54, 39.18],
       [-76.52, 39.18],
       [-76.52, 39.17],
       [-76.54, 39.17]
   ]
});

// update coordinates
var mySource = map.getSource('some id');
mySource.setCoordinates([
    [-76.54335737228394, 39.18579907229748],
    [-76.52803659439087, 39.1838364847587],
    [-76.5295386314392, 39.17683392507606],
    [-76.54520273208618, 39.17876344106642]
]);

// update url and coordinates simultaneously
mySource.updateImage({
   url: 'https://www.mapbox.com/images/bar.png',
   coordinates: [
       [-76.54335737228394, 39.18579907229748],
       [-76.52803659439087, 39.1838364847587],
       [-76.5295386314392, 39.17683392507606],
       [-76.54520273208618, 39.17876344106642]
   ]
})

map.removeSource('some id');  // remove

updateImage

Updates the image URL and, optionally, the coordinates. To avoid having the image flash after changing, set the raster-fade-duration paint property on the raster layer to 0.

Parameters

  • options Object Options object.
    • options.url string? Required image URL.
    • options.coordinates Array<Array<number»? Four geographical coordinates, represented as arrays of longitude and latitude numbers, which define the corners of the image. The coordinates start at the top left corner of the image and proceed in clockwise order. They do not have to represent a rectangle.

Returns ImageSource this

setCoordinates

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

Parameters

  • coordinates Array<Array<number» Four geographical coordinates, represented as arrays of longitude and latitude numbers, which define the corners of the image. The coordinates start at the top left corner of the image and proceed in clockwise order. They do not have to represent a rectangle.

Returns ImageSource this

CanvasSourceOptions

Options to add a canvas source type to the map.

Type: Object

Properties

  • type string Source type. Must be "canvas".
  • canvas (string | HTMLCanvasElement) Canvas source from which to read pixels. Can be a string representing the ID of the canvas element, or the HTMLCanvasElement itself.
  • coordinates Array<Array<number» Four geographical coordinates denoting where to place the corners of the canvas, specified in [longitude, latitude] pairs.
  • animate boolean? Whether the canvas source is animated. If the canvas is static (i.e. pixels do not need to be re-read on every frame), animate should be set to false to improve performance.

CanvasSource

Extends ImageSource

A data source containing the contents of an HTML canvas. See CanvasSourceOptions for detailed documentation of options.

Parameters

  • id string
  • options CanvasSourceSpecification
  • dispatcher Dispatcher
  • eventedParent Evented

Examples

// add to map
map.addSource('some id', {
   type: 'canvas',
   canvas: 'idOfMyHTMLCanvas',
   animate: true,
   coordinates: [
       [-76.54, 39.18],
       [-76.52, 39.18],
       [-76.52, 39.17],
       [-76.54, 39.17]
   ]
});

// update
var mySource = map.getSource('some id');
mySource.setCoordinates([
    [-76.54335737228394, 39.18579907229748],
    [-76.52803659439087, 39.1838364847587],
    [-76.5295386314392, 39.17683392507606],
    [-76.54520273208618, 39.17876344106642]
]);

map.removeSource('some id');  // remove

play

Enables animation. The image will be copied from the canvas to the map on each frame.

pause

Disables animation. The map will display a static copy of the canvas image.

getCanvas

Returns the HTML canvas element.

Returns HTMLCanvasElement The HTML canvas element.

setCoordinates

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

Parameters

  • coordinates Array<Array<number» Four geographical coordinates, represented as arrays of longitude and latitude numbers, which define the corners of the canvas. The coordinates start at the top left corner of the canvas and proceed in clockwise order. They do not have to represent a rectangle.

Returns CanvasSource this

GeoJSONSource

Extends Evented

A source containing GeoJSON. (See the Style Specification for detailed documentation of options.)

Parameters

  • id string
  • options any
  • dispatcher Dispatcher
  • eventedParent Evented

Examples

map.addSource('some id', {
    type: 'geojson',
    data: 'https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_10m_ports.geojson'
});

map.addSource('some id', {
   type: 'geojson',
   data: {
       "type": "FeatureCollection",
       "features": [{
           "type": "Feature",
           "properties": {},
           "geometry": {
               "type": "Point",
               "coordinates": [
                   -76.53063297271729,
                   39.18174077994108
               ]
           }
       }]
   }
});

map.getSource('some id').setData({
  "type": "FeatureCollection",
  "features": [{
      "type": "Feature",
      "properties": { "name": "Null Island" },
      "geometry": {
          "type": "Point",
          "coordinates": [ 0, 0 ]
      }
  }]
});

setData

Sets the GeoJSON data and re-renders the map.

Parameters

  • data (Object | string) A GeoJSON data object or a URL to one. The latter is preferable in the case of large GeoJSON files.

Returns GeoJSONSource this

getClusterExpansionZoom

For clustered sources, fetches the zoom at which the given cluster expands.

Parameters

  • clusterId number The value of the cluster’s cluster_id property.
  • callback Callback<number> A callback to be called when the zoom value is retrieved ((error, zoom) => { ... }).

Returns GeoJSONSource this

getClusterChildren

For clustered sources, fetches the children of the given cluster on the next zoom level (as an array of GeoJSON features).

Parameters

  • clusterId number The value of the cluster’s cluster_id property.
  • callback Callback<Array<GeoJSONFeature» A callback to be called when the features are retrieved ((error, features) => { ... }).

Returns GeoJSONSource this

getClusterLeaves

For clustered sources, fetches the original points that belong to the cluster (as an array of GeoJSON features).

Parameters

  • clusterId number The value of the cluster’s cluster_id property.
  • limit number The maximum number of features to return.
  • offset number The number of features to skip (e.g. for pagination).
  • callback Callback<Array<GeoJSONFeature» A callback to be called when the features are retrieved ((error, features) => { ... }).

Examples

// Retrieve cluster leaves on click
map.on('click', 'clusters', function(e) {
  var features = map.queryRenderedFeatures(e.point, {
    layers: ['clusters']
  });

  var clusterId = features[0].properties.cluster_id;
  var pointCount = features[0].properties.point_count;
  var clusterSource = map.getSource('clusters');

  clusterSource.getClusterLeaves(clusterId, pointCount, 0, function(error, features) {
    // Print cluster leaves in the console
    console.log('Cluster leaves:', error, features);
  })
});

Returns GeoJSONSource this