Mapbox GL JS

Current version: v1.5.0 View changelog

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

Mapbox GL JS is a JavaScript library that uses WebGL to render interactive maps from vector tiles and Mapbox styles. It is part of the Mapbox GL ecosystem, which includes Mapbox Mobile, a compatible renderer written in C++ with bindings for desktop and mobile platforms.

Quickstart

To get started, you need an access token and a style URL. You can choose from one of our professionally designed styles or create your own using Mapbox Studio.

Include the JavaScript and CSS files in the <head> of your HTML file.

<script src='https://api.tiles.mapbox.com/mapbox-gl-js/v1.5.0/mapbox-gl.js'></script>
<link href='https://api.tiles.mapbox.com/mapbox-gl-js/v1.5.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>
mapboxgl.accessToken = 'undefined';
var map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/streets-v9'
});
</script>

CSP Directives

As a mitigation for Cross-Site Scripting and other types of web security vulnerabilities, you may use a Content Security Policy (CSP) to specify security policies for your website. If you do, Mapbox GL JS requires the following CSP directives:

worker-src blob: ;
child-src blob: ;
img-src data: blob: ;

Requesting styles from Mapbox or other services will require additional directives. For Mapbox, you can use this connect-src directive:

connect-src https://*.tiles.mapbox.com https://api.mapbox.com https://events.mapbox.com

For strict CSP environments without worker-src blob: ; child-src blob: enabled, there's a separate Mapbox GL JS bundle (mapbox-gl-csp.js and mapbox-gl-csp-worker.js) which requires setting the path to the worker manually:

<script src='https://api.tiles.mapbox.com/mapbox-gl-js/v1.5.0/mapbox-gl-csp.js'></script>
<script>
mapboxgl.workerUrl = "https://api.tiles.mapbox.com/mapbox-gl-js/v1.5.0/mapbox-gl-csp-worker.js";
...
</script>

Mapbox CSS

The CSS referenced in the Quickstart is used to style DOM elements created by Mapbox code. Without the CSS, elements like Popups and Markers won't work.

Including it with a <link> in the head of the document via the Mapbox CDN is the simplest and easiest way to provide the CSS, but it is also bundled in the Mapbox module, meaning that if you have a bundler that can handle CSS, you can import the CSS from mapbox-gl/dist/mapbox-gl.css.

Note too that if the CSS isn't available by the first render, as soon as the CSS is provided, the DOM elements that depend on this CSS should recover.

Was this page helpful?