Getting Started | Mapbox GL JS

Before you get started with Mapbox GL JS, you need to have a Mapbox access token and add Mapbox GL JS to your project using either the CDN or the mapbox-gl npm package.

Prerequisites

To use Mapbox GL JS, you need to have a Mapbox access token. This access token associates your map with a Mapbox account. For more information on creating and using access tokens, see our token management documentation.

Internet Explorer - Browser Support

Starting with v2.0.0, Mapbox GL JS is no longer compatible with any version of Internet Explorer.

If you need to support Internet Explorer, consider using the Static Images API for non-interactive maps or the Static Tiles API with another library like Leaflet for interactive maps.

Import or Install Mapbox-GL-JS

JavaScript


<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Mapbox GL JS map</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.0/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.9.0/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', // container ID
        center: [-74.5, 40], // starting position [lng, lat]. Note that lat must be set between -90 and 90
        zoom: 9 // starting zoom
    });
</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.

To use Mapbox GL JS in your project, you need to import it using the Mapbox GL JS CDN or install the mapbox-gl npm package.

Mapbox CDN

Module bundler

Include the JavaScript and CSS files in the head of your HTML file.The CSS file is required to display the map and make elements like Popups and Markers work.


<script src='https://api.mapbox.com/mapbox-gl-js/v3.9.0/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v3.9.0/mapbox-gl.css' rel='stylesheet' />

Include the following code in the body of your HTML file.


<div id='map' style='width: 400px; height: 300px;'></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', // container ID
	style: 'mapbox://styles/mapbox/streets-v12', // style URL
	center: [-74.5, 40], // starting position [lng, lat]
	zoom: 9, // starting zoom
});
</script>

To see these pieces of code working together in a web app, take a look at our Display a map on a webpage example.

Transpiling

Mapbox GL JS v2 is distributed as an ES6 compatible JavaScript bundle and is compatible with all major modern browsers.

The JavaScript bundle is incompatible with some Babel transforms because of the way it shares code between the main thread and Web Worker. We do this to reduce the bundle size and improve rendering performance. If you are using v2 with a module bundler such as Webpack or Rollup along with a transpiler such as Babel, there are three ways to make it compatible:

Use browserslist to target transpilation to a set of compatible transforms
Explicitly disable transpiling of the Mapbox GL JS bundle
Load and transpile Web Worker code separately at the cost of increasing bundle size and reducing performance.

Targeting transpilation to ES6 with browserslist

If you're using @babel/preset-env in conjunction with browserslist to set target browser environments, consider using the following browserslist queries to select a set of compatible transforms.


"browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all",
      "not safari < 10",
      "not chrome < 51",
      "not android < 5",
      "not ie < 12"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },

This can be specified in your project's package.json or in a .browserslistrc file. See @babel/preset-env docs for more details.

Excluding Mapbox GL JS explicitly from transpilation

If other parts of your application need ES5 transpilation, then consider excluding GL JS explicitly from transpilation. If you are using Webpack, you can use the ! prefix in the import statement to exclude mapbox-gl from being transformed by existing loaders. See Webpack loaders inline usage docs for more details.


import mapboxgl from '!mapbox-gl';

You can also configure this centrally in webpack.config.js by adding the ignore option to Babel.


use: {
  loader: 'babel-loader',
  options: {
    presets: ['my-custom-babel-preset'],
    ..,
    ..,
    ignore: [ './node_modules/mapbox-gl/dist/mapbox-gl.js' ]
  }
}

Loading and transpiling the Web Worker separately

If your application requires ES5 compatibility, then your module bundler needs to be configured to load and transpile Mapbox GL JS's Web Worker separately. This comes at the cost of significantly increasing the bundle size and negatively impacting rendering performance and you should only do this if you have a strong need for supporting legacy browsers. Mapbox GL JS can be configured with bundler specific worker-loader plugins. See webpack-worker-loader and rollup-plugin-worker-loader.

If you are using Webpack, you can configure worker-loader to be used inline when importing mapbox-gl:


import mapboxgl from 'mapbox-gl/dist/mapbox-gl-csp';
import MapboxWorker from 'worker-loader!mapbox-gl/dist/mapbox-gl-csp-worker'; // Load worker code separately with worker-loader

mapboxgl.workerClass = MapboxWorker; // Wire up loaded worker to be used instead of the default
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
});

You can also configure worker-loader centrally in webpack.config.js :


module.exports = {
  module: {
    rules: [
      {
        test: /\bmapbox-gl-csp-worker.js\b/i,
        use: { loader: 'worker-loader' }
      }
    ]
  }
};

and then integrate the Webpack loaded worker with Mapbox GL JS:


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

mapboxgl.workerClass = MapboxWorker;
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
});