Installation | 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.

Account requirements

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.

Browser support

Mapbox GL JS is supported in most modern browsers. 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 Mapbox.js for interactive maps.

To test client support for your applications, see our Check Mapbox GL JS browser support example.

Quickstart

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.3.0/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v3.3.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>
undefinedmapboxgl.accessToken = 'undefined';
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
});

Was this page helpful?

Account requirements​

Browser support​

Quickstart​

Transpiling​

Targeting transpilation to ES6 with browserslist​

Excluding Mapbox GL JS explicitly from transpilation​

Loading and transpiling the Web Worker separately​