MapLibre GL JS
API Reference
On This Page
Table of Contents
VideoSource
Extends ImageSource
A data source containing video. (See the Style Specification for detailed documentation of options.)
Parameters
id
stringoptions
VideoSourceSpecificationdispatcher
DispatchereventedParent
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
**(ImageSourceSpecificationVideoSourceSpecification CanvasSourceSpecification)** dispatcher
DispatchereventedParent
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 theHTMLCanvasElement
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 tofalse
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
stringoptions
CanvasSourceSpecificationdispatcher
DispatchereventedParent
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
stringoptions
anydispatcher
DispatchereventedParent
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’scluster_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’scluster_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’scluster_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