Mapbox GL JS from scratch to mastery: 2025-2026 practical guide

1. Introduction and positioning

Mapbox GL JS is a high-performance JavaScript map library based on WebGL for building interactive 2D/3D vector map applications.Unlike traditional maps that use image tiles, Mapbox GL uses Vector Tiles + GPU rendering to achieve:

Live style changes
Smooth zoom
3D architecture
terrain
Dynamic data visualization

Therefore in Data visualization, city digital twin, logistics monitoring, large-screen visualization Very common in scenarios such as this.

Comparison of mainstream WebGIS libraries

Library	Features	Applicable scenarios
Leaflet	Lightweight, simple, with many plug-ins	Simple map application
OpenLayers	The most complete GIS function, supporting OGC standards	Professional GIS system
MapLibre GL	Open source fork of Mapbox v1	Free vector maps
Mapbox GL JS	Best visual effects, strong 3D	Business map visualization
Cesium	Focus on 3D Earth	Digital Earth, Aerospace

Simple understanding:

Leaflet → lightweight map
OpenLayers → GIS Tools
Mapbox → Visual Map
Cesium → 3D Earth

Mapbox GL JS v3 capabilities used here

The CDN examples use version 3.19.0. These are relevant capabilities, not a claim that every feature first appeared in v3; check style and service prerequisites against the matching documentation.

1）Standard Style

A new default map style with a more realistic visual representation.

2) 3D lighting system

Realistic shadows of buildings
Sunshine simulation
Light angle control

3）3D Terrain

Realistic terrain rendering.

4) New Camera API

Smoother camera controls.

5) Performance improvement

GPU rendering optimization, large-scale data is smoother.

What can you do after studying?

For example:

Real-time logistics monitoring

车辆位置 + 轨迹动画

City Digital Twin

3D 建筑 + 实时数据

Data visualization big screen

热力图 + 聚合点

Immersive city tour

3D 地形 + fly 动画

2. Development environment setup

Method 1: CDN (quickest way to get started)

Suitable for quick experience

html

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

Method 2: Vite + npm (recommended)

Initialization project:

bash

npm create vite@latest mapbox-demo
cd mapbox-demo
npm install

Install Mapbox:

bash

npm install mapbox-gl

main.js：

javascript

import mapboxgl from "mapbox-gl";
import "mapbox-gl/dist/mapbox-gl.css";

Start:

npm run dev

Method 3: Pure ESM

html

<script type="module">
  import mapboxgl from "https://cdn.skypack.dev/mapbox-gl";
</script>

Get Mapbox Token

Need to register an account:

https://mapbox.com

Get:

Access Token

Minimal runnable example

html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Mapbox Demo</title>

    <link
      href="https://api.mapbox.com/mapbox-gl-js/v3.19.0/mapbox-gl.css"
      rel="stylesheet"
    />

    <style>
      body {
        margin: 0;
      }
      #map {
        width: 100vw;
        height: 100vh;
      }
    </style>
  </head>

  <body>
    <div id="map"></div>

    <script src="https://api.mapbox.com/mapbox-gl-js/v3.19.0/mapbox-gl.js"></script>

    <script>
      mapboxgl.accessToken = "YOUR_TOKEN";

      const map = new mapboxgl.Map({
        container: "map",
        style: "mapbox://styles/mapbox/standard",
        center: [-118.24, 34.05],
        zoom: 10,
      });
    </script>
  </body>
</html>

3. Quick overview of core concepts

It's important to understand the core structure of Mapbox.

Map

Map is a map instance

javascript

const map = new mapboxgl.Map({
  container: "map",
  style: "mapbox://styles/mapbox/standard",
});

Camera

Control the map perspective.

javascript

map.flyTo({
  center: [116.39, 39.9],
  zoom: 12,
  pitch: 60,
});

Style

Map style system.

Follow Mapbox Style Spec

javascript

style: "mapbox://styles/mapbox/satellite-streets-v12";

Sources

data source.

Common types:

geojson
vector
raster
raster-dem

Example:

javascript

map.addSource("points", {
  type: "geojson",
  data: "points.geojson",
});

Layers

Layers are used to display data.

Common types:

fill
line
circle
symbol
fill-extrusion

Example:

javascript

map.addLayer({
  id: "point-layer",
  type: "circle",
  source: "points",
});

Expressions

Mapbox’s data-driven styling system

javascript

'circle-color':[
'match',
['get','type'],
'restaurant','#ff0000',
'park','#00ff00',
'#0000ff'
]

Controls

Map control:

NavigationControl
GeolocateControl
ScaleControl

Example:

javascript

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

Information pop-up window.

javascript

new mapboxgl.Popup().setLngLat([116, 39]).setHTML("<h3>北京</h3>").addTo(map);

4. Make your first cool map in 5 minutes

Complete example:

html

<div id="map"></div>

<script>
  mapboxgl.accessToken = "TOKEN";

  const map = new mapboxgl.Map({
    container: "map",
    style: "mapbox://styles/mapbox/standard",
    center: [-118.24, 34.05],
    zoom: 10,
    pitch: 60,
    bearing: -20,
  });

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

  map.addControl(
    new mapboxgl.GeolocateControl({
      positionOptions: { enableHighAccuracy: true },
      trackUserLocation: true,
    }),
  );

  map.on("load", () => {
    map.addSource("mapbox-dem", {
      type: "raster-dem",
      url: "mapbox://mapbox.mapbox-terrain-dem-v1",
    });

    map.setTerrain({
      source: "mapbox-dem",
      exaggeration: 1.5,
    });
  });
</script>

Effect:

3D terrain
control
tilt angle

5. Intermediate Advanced

5.1 Switch map style

javascript

map.setStyle("mapbox://styles/mapbox/satellite-streets-v12");

Common:

standard
streets
satellite
light
dark

5.2 Add GeoJSON data

javascript

map.addSource("earthquakes", {
  type: "geojson",
  data: "earthquake.geojson",
});

map.addLayer({
  id: "earthquake-layer",
  type: "circle",
  source: "earthquakes",
  paint: {
    "circle-radius": 6,
    "circle-color": "red",
  },
});

5.3 Data-driven style

javascript

'circle-radius':[
'interpolate',
['linear'],
['zoom'],
5,2,
15,20
]

5.4 3D Architecture

javascript

map.addLayer({
  id: "3d-buildings",
  source: "composite",
  "source-layer": "building",
  type: "fill-extrusion",
  paint: {
    "fill-extrusion-height": ["get", "height"],
    "fill-extrusion-color": "#aaa",
  },
});

5.5 Interaction

Click event:

javascript

map.on("click", "poi-layer", (e) => {
  new mapboxgl.Popup().setLngLat(e.lngLat).setHTML("POI").addTo(map);
});

5.6 flyTo animation

javascript

map.flyTo({
  center: [121.47, 31.23],
  zoom: 12,
  pitch: 60,
  speed: 0.8,
});

5.7 Aggregation

javascript

map.addSource("points", {
  type: "geojson",
  data: "points.geojson",
  cluster: true,
  clusterRadius: 50,
});

6. Advanced practice: urban real-time traffic monitoring large screen

Project features:

实时车辆
交通热力图
轨迹动画
3D 建筑
POI 筛选
时间轴回放

Project structure

mapbox-traffic
 ├ index.html
 ├ main.js
 ├ style.css
 └ data
     └ vehicles.geojson

Load vehicle data

javascript

map.addSource("vehicles", {
  type: "geojson",
  data: "data/vehicles.geojson",
});

Vehicle layer

javascript

map.addLayer({
  id: "vehicle-layer",
  type: "circle",
  source: "vehicles",
  paint: {
    "circle-radius": 5,
    "circle-color": "#ff0000",
  },
});

Aggregate a large number of vehicles

javascript

cluster: true;

heat map

javascript

map.addLayer({
  id: "traffic-heat",
  type: "heatmap",
  source: "vehicles",
  paint: {
    "heatmap-radius": 20,
  },
});

vehicle trajectory

javascript

map.addLayer({
  id: "routes",
  type: "line",
  source: "routes",
  paint: {
    "line-color": "#00ffff",
    "line-width": 4,
  },
});

WebSocket real-time updates

javascript

socket.onmessage = (e) => {
  const data = JSON.parse(e.data);

  map.getSource("vehicles").setData(data);
};

Vue UI linkage

javascript

watch(selectedVehicle, (id) => {
  map.flyTo({
    center: vehicleMap[id],
  });
});

7. Production-level best practices

Token security

Don't hardcode the token.

Suggestions:

.env

Performance optimization

Reduce the number of layers.

推荐 < 100

Use:

promoteId
cluster
vector tiles

Mobile terminal adaptation

javascript

antialias: true;

Adapted to touch.

FAQ

Map white screen

Usually:

token 错误
style 错误

Wrong coordinates

Mapbox uses:

[longitude, latitude]

8. Learning resources

Official documentation:

https://docs.mapbox.com/mapbox-gl-js/

Example library:

Mapbox Examples

Recommended advanced directions:

Mapbox + React
Mapbox + Deck.gl
Mapbox + Three.js
Mapbox + PMTiles

9. Conclusion

Suggested learning paths for Mapbox GL JS:

CDN demo
↓
Vite 项目
↓
GeoJSON 数据
↓
表达式样式
↓
3D 地形
↓
实时数据
↓
完整地图产品

Suggestions:

1️⃣ Fork official examples
2️⃣ Transformation demo
3️⃣ Publish your own map project

When you become proficient in Mapbox, you will be able to develop:

City Digital Twin
Logistics Monitoring
Data Visualization Map
Immersive WebGIS

Map development is The intersection of front-end + GIS + visualization 。

1. Introduction and positioning ​

Comparison of mainstream WebGIS libraries ​

Mapbox GL JS v3 capabilities used here ​

What can you do after studying? ​

2. Development environment setup ​

Method 1: CDN (quickest way to get started) ​

Method 2: Vite + npm (recommended) ​

Method 3: Pure ESM ​

Get Mapbox Token ​

Minimal runnable example ​

3. Quick overview of core concepts ​

Map ​

Camera ​

Style ​

Sources ​

Layers ​

Expressions ​

Controls ​

Popup ​

4. Make your first cool map in 5 minutes ​

5. Intermediate Advanced ​

5.1 Switch map style ​

5.2 Add GeoJSON data ​

5.3 Data-driven style ​

5.4 3D Architecture ​

5.5 Interaction ​

5.6 flyTo animation ​

5.7 Aggregation ​

6. Advanced practice: urban real-time traffic monitoring large screen ​

Project structure ​

Load vehicle data ​

Vehicle layer ​

Aggregate a large number of vehicles ​

heat map ​

vehicle trajectory ​

WebSocket real-time updates ​

Vue UI linkage ​

7. Production-level best practices ​

Token security ​

Performance optimization ​

Mobile terminal adaptation ​

FAQ ​

Map white screen ​

Wrong coordinates ​

8. Learning resources ​

9. Conclusion ​

1. Introduction and positioning

Comparison of mainstream WebGIS libraries

Mapbox GL JS v3 capabilities used here

What can you do after studying?

2. Development environment setup

Method 1: CDN (quickest way to get started)

Method 2: Vite + npm (recommended)

Method 3: Pure ESM

Get Mapbox Token

Minimal runnable example

3. Quick overview of core concepts

Map

Camera

Style

Sources

Layers

Expressions

Controls

Popup

4. Make your first cool map in 5 minutes

5. Intermediate Advanced

5.1 Switch map style

5.2 Add GeoJSON data

5.3 Data-driven style

5.4 3D Architecture

5.5 Interaction

5.6 flyTo animation

5.7 Aggregation

6. Advanced practice: urban real-time traffic monitoring large screen

Project structure

Load vehicle data

Vehicle layer

Aggregate a large number of vehicles

heat map

vehicle trajectory

WebSocket real-time updates

Vue UI linkage

7. Production-level best practices

Token security

Performance optimization

Mobile terminal adaptation

FAQ

Map white screen

Wrong coordinates

8. Learning resources

9. Conclusion