Properties and options

Gets and sets the map's access token.

Returns

string: The currently set access token.

Example


mapboxgl.accessToken = myAccessToken;

Example: Display a map

Was this section on accessToken helpful?

AnimationOptions

githubsrc/ui/camera.ts

Options common to map movement methods that involve animation, such as Map#panBy and Map#easeTo, controlling the duration and easing function of the animation. All properties are optional.

Properties

animate(boolean): If false , no animation will occur.

curve(number): The zooming "curve" that will occur along the flight path. A high value maximizes zooming for an exaggerated animation, while a low value minimizes zooming for an effect closer to Map#easeTo . 1.42 is the average value selected by participants in the user study discussed in van Wijk (2003) . A value of Math.pow(6, 0.25) would be equivalent to the root mean squared average velocity. A value of 1 would produce a circular motion. If minZoom is specified, this option will be ignored.

duration(number): The animation's duration, measured in milliseconds.

easing(Function): A function taking a time in the range 0..1 and returning a number where 0 is the initial state and 1 is the final state.

essential(boolean): If true , then the animation is considered essential and will not be affected by prefers-reduced-motion .

maxDuration(number): The animation's maximum duration, measured in milliseconds. If duration exceeds maximum duration, it resets to 0.

minZoom(number): The zero-based zoom level at the peak of the flight path. If this option is specified, curve will be ignored.

offset(PointLike): The target center's offset relative to real map container center at the end of animation.

preloadOnly(boolean): If true , it will trigger tiles loading across the animation path, but no animation will occur.

screenSpeed(number): The average speed of the animation measured in screenfuls per second, assuming a linear timing curve. If speed is specified, this option is ignored.

speed(number): The average speed of the animation defined in relation to curve . A speed of 1.2 means that the map appears to move along the flight path by 1.2 times curve screenfuls every second. A screenful is the map's visible span. It does not correspond to a fixed physical distance, but varies by zoom level.

Was this section on AnimationOptions helpful?

baseApiUrl

Gets and sets the map's default API URL for requesting tiles, styles, sprites, and glyphs.

Type

Returns

string: The current base API URL.

Example


mapboxgl.baseApiUrl = 'https://api.mapbox.com';

Was this section on baseApiUrl helpful?

CameraOptions

githubsrc/ui/camera.ts

Options common to Map#jumpTo, Map#easeTo, and Map#flyTo, controlling the desired location, zoom, bearing, and pitch of the camera. All properties are optional, and when a property is omitted, the current camera value for that property will remain unchanged.

Type

Properties

around(LngLatLike): The location serving as the origin for a change in zoom , pitch and/or bearing . This location will remain at the same screen position following the transform. This is useful for drawing attention to a location that is not in the screen center. center is ignored if around is included.

bearing(number): The desired bearing in degrees. The bearing is the compass direction that is "up". For example, bearing: 90 orients the map so that east is up.

center(LngLatLike): The location to place at the screen center.

padding(PaddingOptions): Dimensions in pixels applied on each side of the viewport for shifting the vanishing point. Note that when padding is used with jumpTo , easeTo , and flyTo , it also sets the global map padding as a side effect, affecting all subsequent camera movements until the padding is reset. To avoid this, add the retainPadding: false option.

pitch(number): The desired pitch in degrees. The pitch is the angle towards the horizon measured in degrees with a range between 0 and 85 degrees. For example, pitch: 0 provides the appearance of looking straight down at the map, while pitch: 60 tilts the user's perspective towards the horizon. Increasing the pitch value is often used to display 3D objects.

retainPadding(boolean): If false , the value provided with the padding option will not be retained as the global map padding. This is true by default.

zoom(number): The desired zoom level.

Example


// set the map's initial perspective with CameraOptions
const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v11',
    center: [-73.5804, 45.53483],
    pitch: 60,
    bearing: -60,
    zoom: 10
});

Was this section on CameraOptions helpful?

clearPrewarmedResources

Clears up resources that have previously been created by mapboxgl.prewarm(). Note that this is typically not necessary. You should only call this function if you expect the user of your app to not return to a Map view at any point in your application.

Example


mapboxgl.clearPrewarmedResources();

Was this section on clearPrewarmedResources helpful?

clearStorage

githubsrc/style/style_layer/custom_style_layer.ts

Clears browser storage used by this library. Using this method flushes the Mapbox tile cache that is managed by this library. Tiles may still be cached by the browser in some cases.

This API is supported on browsers where the Cache API is supported and enabled. This includes all major browsers when pages are served over https://, except Internet Explorer and Edge Mobile.

When called in unsupported browsers or environments (private or incognito mode), the callback will be called with an error argument.

Parameters

callback(Function)Called with an error argument if there is an error.

Example


mapboxgl.clearStorage();

Was this section on clearStorage helpful?

CustomLayerInterface

Interface for custom style layers. This is a specification for implementers to model: it is not an exported method or class.

Custom layers allow a user to render directly into the map's GL context using the map's camera. These layers can be added between any regular layers using Map#addLayer.

Custom layers must have a unique id and must have the type of "custom". They must implement render and may implement prerender, onAdd and onRemove. They can trigger rendering using Map#triggerRepaint and they should appropriately handle Map.event:webglcontextlost and Map.event:webglcontextrestored.

The renderingMode property controls whether the layer is treated as a "2d" or "3d" map layer. Use:

"renderingMode": "3d" to use the depth buffer and share it with other layers
"renderingMode": "2d" to add a layer with no depth. If you need to use the depth buffer for a "2d" layer you must use an offscreen framebuffer and CustomLayerInterface#prerender.

Properties

id(string): A unique layer id.

renderingMode(string): Either "2d" or "3d" . Defaults to "2d" .

type(string): The layer's type. Must be "custom" .

Example


// Custom layer implemented as ES6 class
class NullIslandLayer {
    constructor() {
        this.id = 'null-island';
        this.type = 'custom';
        this.renderingMode = '2d';
    }

    onAdd(map, gl) {
        const vertexSource = `
        uniform mat4 u_matrix;
        void main() {
            gl_Position = u_matrix * vec4(0.5, 0.5, 0.0, 1.0);
            gl_PointSize = 20.0;
        }`;

        const fragmentSource = `
        void main() {
            gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
        }`;

        const vertexShader = gl.createShader(gl.VERTEX_SHADER);
        gl.shaderSource(vertexShader, vertexSource);
        gl.compileShader(vertexShader);
        const fragmentShader = gl.createShader(gl.FRAGMENT_SHADER);
        gl.shaderSource(fragmentShader, fragmentSource);
        gl.compileShader(fragmentShader);

        this.program = gl.createProgram();
        gl.attachShader(this.program, vertexShader);
        gl.attachShader(this.program, fragmentShader);
        gl.linkProgram(this.program);
    }

    render(gl, matrix) {
        gl.useProgram(this.program);
        gl.uniformMatrix4fv(gl.getUniformLocation(this.program, "u_matrix"), false, matrix);
        gl.drawArrays(gl.POINTS, 0, 1);
    }
}

map.on('load', () => {
    map.addLayer(new NullIslandLayer());
});

Instance Members

Was this section on CustomLayerInterface helpful?

FreeCameraOptions

githubsrc/ui/free_camera.ts

Options for accessing physical properties of the underlying camera entity. Direct access to these properties allows more flexible and precise controlling of the camera. These options are also fully compatible and interchangeable with CameraOptions. All fields are optional. See Map#setFreeCameraOptions and Map#getFreeCameraOptions.

new FreeCameraOptions(position: MercatorCoordinate, orientation: quat)

Parameters

position(MercatorCoordinate)Position of the camera in slightly modified web mercator coordinates.

The size of 1 unit is the width of the projected world instead of the "mercator meter". Coordinate [0, 0, 0] is the north-west corner and [1, 1, 0] is the south-east corner.
Z coordinate is conformal and must respect minimum and maximum zoom values.
Zoom is automatically computed from the altitude (z).

orientation(quat)Orientation of the camera represented as a unit quaternion [x, y, z, w] in a left-handed coordinate space. Direction of the rotation is clockwise around the respective axis. The default pose of the camera is such that the forward vector is looking up the -Z axis. The up vector is aligned with north orientation of the map: forward: [0, 0, -1] up: [0, -1, 0] right [1, 0, 0] Orientation can be set freely but certain constraints still apply:

Orientation must be representable with only pitch and bearing.
Pitch has an upper limit

Example


const camera = map.getFreeCameraOptions();

const position = [138.72649, 35.33974];
const altitude = 3000;

camera.position = mapboxgl.MercatorCoordinate.fromLngLat(position, altitude);
camera.lookAtPoint([138.73036, 35.36197]);

map.setFreeCameraOptions(camera);

Instance Members

Was this section on FreeCameraOptions helpful?

getRTLTextPluginStatus

Gets the map's RTL text plugin status. The status can be unavailable (not requested or removed), loading, loaded, or error. If the status is loaded and the plugin is requested again, an error will be thrown.

Example


const pluginStatus = mapboxgl.getRTLTextPluginStatus();

Was this section on getRTLTextPluginStatus helpful?

maxParallelImageRequests

Gets and sets the maximum number of images (raster tiles, sprites, icons) to load in parallel. 16 by default. There is no maximum value, but the number of images affects performance in raster-heavy maps.

Type

Returns

number: Number of parallel requests currently configured.

Example


mapboxgl.maxParallelImageRequests = 10;

Was this section on maxParallelImageRequests helpful?

PaddingOptions

githubsrc/ui/camera.ts

Options for setting padding on calls to methods such as Map#jumpTo, Map#easeTo, Map#flyTo, Map#fitBounds, Map#fitScreenCoordinates, and Map#setPadding. Adjust these options to set the amount of padding in pixels added to the edges of the canvas. Set a uniform padding on all edges or individual values for each edge. All properties of this object must be non-negative integers. Note that when padding is used with fitBounds, flyTo, or similar methods, it also sets the global map padding as a side effect, affecting all subsequent camera movements until the padding is reset.

Type

Properties

bottom(number): Padding in pixels from the bottom of the map canvas.

left(number): Padding in pixels from the left of the map canvas.

right(number): Padding in pixels from the right of the map canvas.

top(number): Padding in pixels from the top of the map canvas.

Example


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


const bbox = [[-79, 43], [-73, 45]];
map.fitBounds(bbox, {
    padding: 20
});

Was this section on PaddingOptions helpful?

prewarm

Initializes resources like WebWorkers that can be shared across maps to lower load times in some situations. mapboxgl.workerUrl and mapboxgl.workerCount, if being used, must be set before prewarm() is called to have an effect.

By default, the lifecycle of these resources is managed automatically, and they are lazily initialized when a Map is first created. Invoking prewarm() creates these resources ahead of time and ensures they are not cleared when the last Map is removed from the page. This allows them to be re-used by new Map instances that are created later. They can be manually cleared by calling mapboxgl.clearPrewarmedResources(). This is only necessary if your web page remains active but stops using maps altogether. prewarm() is idempotent and has guards against being executed multiple times, and any resources allocated by prewarm() are created synchronously.

This is primarily useful when using Mapbox GL JS maps in a single page app, in which a user navigates between various views, resulting in constant creation and destruction of Map instances.

Example


mapboxgl.prewarm();

Was this section on prewarm helpful?

RequestParameters

githubsrc/util/ajax.ts

A RequestParameters object to be returned from Map.options.transformRequest callbacks.

Type

Properties

body(string): Request body.

collectResourceTiming(boolean): If true, Resource Timing API information will be collected for these transformed requests and returned in a resourceTiming property of relevant data events.

credentials(string): 'same-origin'|'include' Use 'include' to send cookies with cross-origin requests.

headers(Object): The headers to be sent with the request.

method(string): Request method 'GET' | 'POST' | 'PUT' .

referrerPolicy(string): A string representing the request's referrerPolicy. For more information and possible values, see the Referrer-Policy HTTP header page .

type(string): Response body type to be returned 'string' | 'json' | 'arrayBuffer' .

url(string): The URL to be requested.

Example


// use transformRequest to modify requests that begin with `http://myHost`
const map = new Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v11',
    transformRequest: (url, resourceType) => {
        if (resourceType === 'Source' && url.indexOf('http://myHost') > -1) {
            return {
                url: url.replace('http', 'https'),
                headers: {'my-custom-header': true},
                credentials: 'include'  // Include cookies for cross-origin requests
            };
        }
    }
});

Was this section on RequestParameters helpful?

setRTLTextPlugin

githubsrc/style/style_image.ts

Sets the map's RTL text plugin. Necessary for supporting the Arabic and Hebrew languages, which are written right-to-left. Mapbox Studio loads this plugin by default.

Parameters

pluginURL(string)URL pointing to the Mapbox RTL text plugin source.

callback(Function)Called with an error argument if there is an error, or no arguments if the plugin loads successfully.

lazy(boolean)If set to true , MapboxGL will defer loading the plugin until right-to-left text is encountered, and right-to-left text will be rendered only after the plugin finishes loading.

Example


mapboxgl.setRTLTextPlugin('https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-rtl-text/v0.2.0/mapbox-gl-rtl-text.js');

Example: Add support for right-to-left scripts

Was this section on setRTLTextPlugin helpful?

StyleImageInterface

Interface for dynamically generated style images. This is a specification for implementers to model: it is not an exported method or class.

Images implementing this interface can be redrawn for every frame. They can be used to animate icons and patterns or make them respond to user input. Style images can implement a StyleImageInterface#render method. The method is called every frame and can be used to update the image.

Properties

data((Uint8Array | Uint8ClampedArray)): Byte array representing the image. To ensure space for all four channels in an RGBA color, size must be width × height × 4.

height(number): Height in pixels.

width(number): Width in pixels.

Example


const flashingSquare = {
    width: 64,
    height: 64,
    data: new Uint8Array(64 * 64 * 4),

    onAdd(map) {
        this.map = map;
    },

    render() {
        // keep repainting while the icon is on the map
        this.map.triggerRepaint();

        // alternate between black and white based on the time
        const value = Math.round(Date.now() / 1000) % 2 === 0  ? 255 : 0;

        // check if image needs to be changed
        if (value !== this.previousValue) {
            this.previousValue = value;

            const bytesPerPixel = 4;
            for (let x = 0; x < this.width; x++) {
                for (let y = 0; y < this.height; y++) {
                    const offset = (y * this.width + x) * bytesPerPixel;
                    this.data[offset + 0] = value;
                    this.data[offset + 1] = value;
                    this.data[offset + 2] = value;
                    this.data[offset + 3] = 255;
                }
            }

            // return true to indicate that the image changed
            return true;
        }
    }
};

map.addImage('flashing_square', flashingSquare);

Instance Members

Example: Add an animated icon to the map.

Was this section on StyleImageInterface helpful?

supported

Test whether the browser supports Mapbox GL JS.

Parameters

options(Object?)

Name	Description
options.failIfMajorPerformanceCaveat `boolean` default: `false`	If `true` , the function will return `false` if the performance of Mapbox GL JS would be dramatically worse than expected (for example, a software WebGL renderer would be used).

Returns

boolean:

Example


// Show an alert if the browser does not support Mapbox GL
if (!mapboxgl.supported()) {
    alert('Your browser does not support Mapbox GL');
}

Example: Check for browser support

Was this section on supported helpful?

version

Gets the version of Mapbox GL JS in use as specified in package.json, CHANGELOG.md, and the GitHub release.

Type

Example


console.log(`Mapbox GL JS v${mapboxgl.version}`);

Was this section on version helpful?

workerClass

Provides an interface for external module bundlers such as Webpack or Rollup to package mapbox-gl's WebWorker into a separate class and integrate it with the library.

Takes precedence over mapboxgl.workerUrl.

Type

Returns

(Object | null): A class that implements the Worker interface.

Example


import mapboxgl from 'mapbox-gl/dist/mapbox-gl-csp';
import MapboxGLWorker from 'mapbox-gl/dist/mapbox-gl-csp-worker';

mapboxgl.workerClass = MapboxGLWorker;

Was this section on workerClass helpful?

workerCount

Gets and sets the number of web workers instantiated on a page with Mapbox GL JS maps. By default, it is set to 2. Make sure to set this property before creating any map instances for it to have effect.

Type

Returns

number: Number of workers currently configured.

Example


mapboxgl.workerCount = 4;

Was this section on workerCount helpful?

workerUrl