Skip to content
Workshop taught w/ Code for Africa at Hacks/Hackers Nairobi
JavaScript HTML
Branch: master
Clone or download
Pull request Compare This branch is 1 commit behind mikelmaron:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Lesson: Interactive Mapping With Mapbox GL JS

Note: More instructions are available in the code

⚙️ Resources for this lesson:

🔗 The code, the data, the lesson -

🔗 Mapbox sign-up -

🔗 Scrollama library

🔗 Map Kibera Schools

🔗 Map Kibera Schools (as CSV)

Note: The data was prepared for you to use. DO NOT USE THIS DATA FOR PUBLISHING. Information on data processing at It needs to be fact-checked and some of it may be out of date, missing or invalid. This data solely is used to demonstrate data-driven styling.

⚙️ Resources to further your knowledge:

🔗 Our awesome glossary from our Doc Queens 👑

🔗 Our Election Guide covers a bunch of our core elements, like expressions and feature-state

🔗 The Guide To Map Design by Amy Lee Walton

1 - Introduction to geo data


A tileset is a collection of raster or vector data broken up into a uniform grid of square tiles at up to 22 preset zoom levels. Tilesets are used in Mapbox libraries and SDKs as a core piece of making maps visible on mobile or in the browser.

Tilesets are made up of vector tiles and are developed for caching, scaling and serving map imagery rapidly. Mapbox web and mobile-ready vector tiles are 75% smaller than a raster tilesets. This results in fast, smooth zooming from the worldview of a map down to street-level detail.

As the name suggests, vector tiles contain vector data instead of the rendered image. They contain geometries and metadata – like road names, place names, house numbers – in a compact, structured format. Vector tiles are rendered only when requested by a client, like a web browser or a mobile app. Rendering happens either in the client.

Mapbox File types:


The CSV (comma-separated values) format is common for table data, like the kind you may use in Excel or other spreadsheets. CSV files aren’t necessarily mappable unless they contain geographic information (like latitude and longitude).

When uploading CSV files, keep the following in mind:

  • Check out the Mapbox Uploads API documentation for the current size limit for CSV files.
  • CSV files must be in UTF-8 encoding.
  • CSV files must contain coordinates (latitude and longitude) when uploading in Mapbox Studio or Mapbox Studio Classic.
  • CSV files are for point data only.


GeoJSON is a file format for map data served by Mapbox web services and APIs. As a subset of the JSON format, it can be parsed in modern software and native to the JavaScript language. There are several open source tools for converting other geospatial data formats to GeoJSON. A few faves:

  • togeojson, a node package for converting KML and GPX (XML formats).
  • ogr2ogr, the ultimate 40-in-1 vector data conversion tool.
  • for creating, converting, and editing GeoJSON.


MBTiles is a file format for storing tilesets. It’s designed so that you can package the potentially thousands of files that make up a tileset and move them around, eventually uploading to Mapbox or using in a web or mobile application. MBTiles is an open specification and is based on the SQLite database. MBTiles can contain raster or vector tilesets.


KML is a file format that is like GeoJSON, but used more commonly in Google products. Like GeoJSON, it can store points, lines, polygons, and other vector data. Unlike GeoJSON, it’s based on XML, rather than JSON. When uploading KML, please note that Mapbox does not support any KML extensions.


GPX, or GPS eXchange format, is a data format commonly created from GPS receivers. You can upload GPX files to your Mapbox account to use in a custom map style. Please note that Mapbox does not support values along lines (for example, elevation and time at various points along a jogging route). A GPX file with values along a line can be uploaded, but Mapbox will ignore any data along the line.


A shapefile, also known as an ESRI shapefile, is a file format for storing geographic vector data. When uploading shapefiles, keep the following in mind:

  • Check out the Mapbox Uploads API documentation for the current size limit for shapefiles. Note that this limit applies to the shapefile’s uncompressed size, not the size of the compressed zip.
  • Shapefiles are composed of several individual files, which should be combined into a single zip file before uploading. Of these files, Mapbox can read shp, shx, dbf, prj, and index files. Any other files you upload with your zip file will be ignored.


A TIFF, or sometimes TIF, is a file format for saving raster images. With Mapbox, a TIFF is often a GeoTIFF, meaning the file is embedded with georeferencing information.

You can upload TIFF files as tilesets in Mapbox Studio and use them in the Mapbox Studio style editor. When uploading a TIFF file, keep in mind the current size limit for TIFF files.

🔺 Geometry types

  • Points
  • Line strings
  • Polygons/multi-polygons
  • Multi-part collections

2 - The Mapbox Ecosystem

Dataset: Edit your data 📝

Tileset: Bake your data into Vector tiles or upload rasters 🗾

Styles: Customize your style in the Studio interface — You can also style your data here 🎨

Libraries: Add your style to applications using one of our Mapbox libraries — You can also style your data here 👩‍💻 (GL JS, IOS SDK…)

3 - The Process

Example 1:

  • Upload you data to Studio to style it
  • Add interaction using Mapbox GL JS

Example 2:

  • Use a core style (dark, light, streets)
  • Add you data on the frontend using Mapbox GL JS
  • Style the data using expressions in Mapbox GL JS

Example 3:

  • Upload the data in dataset editor
  • Edit your data
  • Style it in Studio
  • Export a high-res PNG and do the rest in Photoshop or use as is

4 - Studio

⬜ Tilesets

  • Lightweight collections of vector data
  • Optimized for rendering
  • Not editable but can be styled in the Mapbox Studio style editor.

📂 Files and Uploads

🔗 Mapbox upload limits

⬜ Mapbox-Provided Tilesets

🔗 Mapbox tilesets

🖼️ Core styles

🔗 Mapbox Studio

🖥️ Studio Dashboard

🔗 Mapbox Studio

🔢 Data Type Supported by Studio

🔗 Layers

  • Fill
  • Fill-extrusion
  • Line
  • Circle
  • Symbol
  • Heatmap
  • Hillshade
  • Raster

👐 Hands-on: let’s do some styling

🔗 Studio docs

  • Upload the data into Mapbox
  • Add it to a style
  • Do some data-driven styling

5 - Mapbox GL JS

🔗 Mapbox GL JS Repo

A lot of what we just did in Studio can be done in Mapbox GL JS as well

📑 General Concepts

  • GL JS uses WebGL which allow the browser to access your computers GPUs (Makes it faster)
  • It uses an HTML element called Canvas
  • You can style data, add data, add interactivity and more
  • Maps are just shapes and therefore, any shapes can be uploaded to Mapbox and interacted with (cartogram, rasters)

👐 Hands-on: let’s build a “scrolly-telly” map

🔗 The code


You can’t perform that action at this time.