Skip to main content

Mapbox GL JS

Current version:v3.9.1View changelog

  • check
    Custom map styles
  • check
    Fast vector maps
  • check
    Compatible with other Mapbox tools
InstallgithubContribute on GitHub
Additional Developer Resources

Mapbox GL JS is a client-side JavaScript library for building web maps and web applications with Mapbox's modern mapping technology. You can use Mapbox GL JS to display Mapbox maps in a web browser or client, add user interactivity, and customize the map experience in your application.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Guides</title>
<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
<link href="https://api.mapbox.com/mapbox-gl-js/v3.9.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.9.1/mapbox-gl.js"></script>
<style>
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script>
	// TO MAKE THE MAP APPEAR YOU MUST
	// ADD YOUR ACCESS TOKEN FROM
	// https://account.mapbox.com
	mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
    const map = new mapboxgl.Map({
        container: 'map',
        style: 'mapbox://styles/mapbox/streets-v9',
        projection: 'globe', // Display the map as a globe, since satellite-v9 defaults to Mercator
        zoom: 1,
        center: [30, 15]
    });

    map.addControl(new mapboxgl.NavigationControl());
    map.scrollZoom.disable();

    map.on('style.load', () => {
        map.setFog({}); // Set the default atmosphere style
    });

    // The following values can be changed to control rotation speed:

    // At low zooms, complete a revolution every two minutes.
    const secondsPerRevolution = 240;
    // Above zoom level 5, do not rotate.
    const maxSpinZoom = 5;
    // Rotate at intermediate speeds between zoom levels 3 and 5.
    const slowSpinZoom = 3;

    let userInteracting = false;
    const spinEnabled = true;

    function spinGlobe() {
        const zoom = map.getZoom();
        if (spinEnabled && !userInteracting && zoom < maxSpinZoom) {
            let distancePerSecond = 360 / secondsPerRevolution;
            if (zoom > slowSpinZoom) {
                // Slow spinning at higher zooms
                const zoomDif =
                    (maxSpinZoom - zoom) / (maxSpinZoom - slowSpinZoom);
                distancePerSecond *= zoomDif;
            }
            const center = map.getCenter();
            center.lng -= distancePerSecond;
            // Smoothly animate the map over one second.
            // When this animation is complete, it calls a 'moveend' event.
            map.easeTo({ center, duration: 1000, easing: (n) => n });
        }
    }

    // Pause spinning on interaction
    map.on('mousedown', () => {
        userInteracting = true;
    });
    map.on('dragstart', () => {
        userInteracting = true;
    });

    // When animation is complete, start spinning if there is no ongoing interaction
    map.on('moveend', () => {
        spinGlobe();
    });

    spinGlobe();
</script>

</body>
</html>
This code snippet will not work as expected until you replace YOUR_MAPBOX_ACCESS_TOKEN with an access token from your Mapbox account.

Learn more about how you can use Mapbox GL JS in your own applications on this page. Want to get started right away? See the quickstart guide, or take a look at our examples.

Use cases​

Use cases for Mapbox GL JS include:

  • Visualizing and animating geographic data
  • Querying and filtering features on a map
  • Placing your data between layers of a Mapbox style
  • Dynamically displaying and styling custom client-side data on a map
  • 3D data visualizations and animations
  • Adding markers and popups to maps programmatically

For more inspiration about what you can do with Mapbox GL JS, see our tutorials, examples, and the Mapbox customer showcase page.

Key concepts​

Mapbox GL​

The "GL" in Mapbox GL JS refers to Mapbox GL, a graphics library that renders 2D and 3D Mapbox maps as dynamic visual graphics with OpenGL in any compatible web browser, without using additional plugins.

Client-side rendering​

Mapbox GL JS relies on client-side rendering. Mapbox GL JS maps are dynamically rendered by combining vector tiles with style rules in the browser rather than on a server, which makes it possible to change the maps's style and displayed data in response to user interaction.

The Map class​

The mapboxgl.Map class is the basis of every Mapbox GL JS project. The example code in this section demonstrates the minimum you need to add a map to your page:

mapboxgl.accessToken = '<your access token here>';
const map = new mapboxgl.Map({
  container: 'map', // container ID
  style: 'mapbox://styles/mapbox/streets-v12', // style URL
  center: [-74.5, 40], // starting position [lng, lat]
  zoom: 9 // starting zoom
});
  • accessToken: This Mapbox access token associates your Mapbox GL JS map with a Mapbox account.
  • container: The HTML element in which the map will be placed. In the example above, this element is the <div> with an ID of "map".
  • style: The style URL of the map style being used to determine which tilesets the map includes and how they are styled. The example above uses the Mapbox Streets v12 style. The Mapbox Standard Style is enabled by default when no style option is provided to the Map constructor.
  • center: The coordinates of the map's starting position, in longitude, latitude order.
  • zoom: The zoom level at which the map should be initialized. This can be a whole number or a decimal value.

Layers​

Mapbox GL JS maps can be composed of several layers that provide visual elements and map data. Each layer provides rules about how the renderer should draw certain data in the browser, and the renderer uses these layers to draw the map on the screen.

The Mapbox GL JS addLayer method adds a Mapbox style layer to the map's style. The only required parameter for addLayer is a Mapbox style layer object. It also accepts an optional before parameter, which is the ID of an existing layer to insert the new layer before. If you omit this argument, then the renderer will draw the layer on top of the map.

Ordering layers with Mapbox Standard

Mapbox Standard makes adding your data layers easier through the concept of slots. Slots are predetermined locations in the style where your layer will be added to, such as on top of existing land layers, but below all labels. Learn more about how to specify the order of a layer at runtime for Mapbox Standard.

The following sections describe the elements of a Mapbox style layer object.

Asynchronous​

Since layers in Mapbox GL JS are remote, they are asynchronous. So code that connects to Mapbox GL JS often uses event binding to change the map at the right time. For example:

map.on('load', () => {
  map.addLayer({
    id: 'terrain-data',
    type: 'line',
    source: {
      type: 'vector',
      url: 'mapbox://mapbox.mapbox-terrain-v2'
    },
    'source-layer': 'contour'
  });
});

This example code uses map.on('load', function() { to call map.addLayer only after the map's resources, including the style, have been loaded. If it were to run map.addLayer right away, it would trigger an error because the style to which you would like to add a layer would not exist yet.

Layer source​

You must define a source when you add a new layer. A source accepts a type and a url, excluding GeoJSON sources which do not have a url. There are six types of sources, each with its own properties:

For more information on each source type, explore the Sources section of the Mapbox Style Specification.

Tilesets can include multiple subsets of data called source layers. As an example, the Mapbox Streets tileset contains source layers for roads, parks, and more. To make sure your layers are referencing the correct source layers, your layer object also needs to include a source-layer (often the name of the original file). See this example:

map.on('load', () => {
  map.addLayer({
    id: 'rpd_parks',
    type: 'fill',
    source: {
      type: 'vector',
      url: 'mapbox://mapbox.3o7ubwm8'
    },
    'source-layer': 'RPD_Parks'
  });
});
addSource()

You can also add sources using the Mapbox GL JS addSource method. There is no difference in map performance when using this alternative method, but it is sometimes preferable to keep code more readable.

Layout and paint properties​

Layers feature two properties that enable data styling: paint and layout. These are used to define how data will be rendered on the map. layout properties refer to placement and visibility, among other high-level preferences, and are applied early in the rendering process. paint properties are more fine-grained style attributes like opacity, color, and translation. They are less processing-intensive and are rendered later.

The following code adds a layer to a map and styles the data with a green fill:

map.on('load', () => {
  map.addLayer({
    id: 'rpd_parks',
    type: 'fill',
    source: {
      type: 'vector',
      url: 'mapbox://mapbox.3o7ubwm8'
    },
    'source-layer': 'RPD_Parks',
    layout: {
      visibility: 'visible'
    },
    paint: {
      'fill-color': 'rgba(61,153,80,0.55)'
    }
  });
});

The final product for the code snippet above could be a map zoomed to show San Francisco with parks shown as green polygons. The RPD_Parks layer could contain vector polygons from the city's park lands data.

addLayer()

If you added your source using the alternative addSource method, you will need to include the source id as the source in addLayer.

Camera​

The camera is the map's field of view. Mapbox GL JS provides the following parameters for adjusting the camera's perspective: center, zoom, bearing (the visual rotation of the map), and pitch (the visual tilt of the map). The map's initial perspective, jumpTo, easeTo, and flyTo all use common camera options.

PLAYGROUND
Location Helper

To experiment with camera pitch, bearing, tilt, and zoom and get values to use in your code, try our Location Helper tool.

Use Mapbox GL JS with other tools​

Mapbox GL JS works well with many other Mapbox tools. You can use your own data in a map, create your own custom map style, add interactivity, and more.

Use your own data​

With Mapbox GL JS, you have access to Mapbox tilesets that provide a large amount of geographic data. You can also upload your own data using Mapbox Studio, Mapbox Tiling Service, or the Uploads API, then access and display it in your Mapbox GL JS map.

Style your maps​

You can use any Mapbox-owned style like Mapbox Streets to style your map. Or you can use your own custom styles created in Mapbox Studio. For more examples of Mapbox-designed and custom map styles being used in Mapbox GL JS maps, see our Examples page.

Interactivity​

Third party tools allow you add additional interactivity to your Mapbox GL JS map. For example, you can do spatial analysis in your Mapbox GL JS map using Turf.js, add a 3D model to your map using three.js, or create animations that respond to sounds in your user's environment using the Web Audio API. For more ways to use Mapbox GL JS with various third-party tools, see our Examples page.

Mapbox GL JS also supports many plugins that you can use to add interactive elements to your web map. There are plugins for adding interactive drawing tools, adding inset maps, integrating with the Mapbox Geocoding API and the Mapbox Directions API, and more. Explore the Mapbox GL JS plugins page for more details.

Mapbox web services APIs​

Mapbox GL JS is an excellent starting point for apps that use one or more Mapbox web services APIs. For example, you can use the Directions API to visualize turn-by-turn directions on a map, or the Isochrone API to visualize estimated travel times. For more examples of ways to use Mapbox web services APIs with Mapbox GL JS, see our Tutorials page and our Mapbox GL JS examples page.

JavaScript frameworks​

Mapbox GL JS can be used with various JavaScript frameworks, including React. To learn more about using Mapbox GL JS with React, see the Use Mapbox GL JS in a React app tutorial.

Attribution​

When you create a map with Mapbox GL JS, it automatically includes attribution on the bottom right corner of the map. For additional display options, see the API documentation for AttributionControl. For more details on what kinds of attribution Mapbox requires and why, see the Attribution guide.

Additional Developer Resources
Was this page helpful?