Mapbox GL JS

Current version: v2.4.1 View changelog

  • Custom map styles
  • Fast vector maps
  • Compatible with other Mapbox tools

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.

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.

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-v11', // 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 v11 style.
  • 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. 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.

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.