ExpressMaps Blog

How to switch from Mapbox GL JS to MapLibre GL JS

How to switch from Mapbox GL JS to MapLibre GL JS
November 13th, 2026
Tom Jenks

If your site still runs Mapbox GL JS, you have probably noticed two things. Version 2 and later need a Mapbox access token and bill per map load, and version 1.x has not had a release in years. MapLibre GL JS is the open-source continuation of Mapbox GL JS 1.x. It is actively maintained, free to use under a BSD licence, and close enough to the original API that most projects move across in under an hour.

This guide covers the switch step by step, including the parts that trip people up.

Why switch

  • No token, no lock-in. MapLibre works with any tile provider that publishes a style document, including ExpressMaps, a self-hosted tile server or several providers at once.
  • Active development. Since the fork, MapLibre has added globe view, terrain improvements and steady performance work, with regular releases.
  • Same mental model. Sources, layers, expressions, markers and popups work the way you already know.

Step 1: swap the library

With script tags, replace the Mapbox files with MapLibre's:

<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.css">
<script src="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.js"></script>

With npm, run npm uninstall mapbox-gl then npm install maplibre-gl, and change your imports from mapbox-gl to maplibre-gl, including the CSS import.

Step 2: rename the global and drop the token

Every mapboxgl. becomes maplibregl., and the accessToken line goes:

// Before
mapboxgl.accessToken = "pk.eyJ...";
var map = new mapboxgl.Map({ container: "map", style: "mapbox://styles/mapbox/streets-v12" });

// After
var map = new maplibregl.Map({
  container: "map",
  style: "https://tiles.expressmaps.com/styles/standard.json?key=YOUR_API_KEY"
});

Step 3: replace the style URL

mapbox:// URLs only resolve against Mapbox's servers, so point the style option at a full HTTPS style URL instead. ExpressMaps has ten ready-made styles; Standard is the closest match to Mapbox Streets, Darklands to Mapbox Dark and Subtle or Greyscale to Mapbox Light. The full list of URLs is on the MapLibre integration page.

What to check afterwards

  • Layer IDs. If your code inserts layers with beforeId (for example below "waterway-label"), those IDs belong to the Mapbox style. Open the new style JSON, find the first symbol layer and use its ID instead.
  • Fonts in your own layers. A text-font such as "DIN Pro Medium" exists only on Mapbox's font server. Use one of the fonts the new style provides; ours include Roboto, Noto Sans and Open Sans.
  • Mapbox-only features. Mapbox Standard style lighting, the Mapbox Search and Directions plugins and Mapbox's own geocoder need replacements. Most other plugins written for GL JS 1.x work with MapLibre unchanged.
  • Attribution. Remove any hand-written Mapbox credit. The attribution control picks up "© OpenStreetMap contributors" from the new style automatically.
  • Re-adding layers after a style change. As in Mapbox, setStyle replaces every layer. Listen for style.load and add your sources and layers there so they survive a switch.

Using React or Leaflet?

react-map-gl supports MapLibre directly: import from react-map-gl/maplibre and pass the style URL as mapStyle. Our React guide has both that and a plain component. If your project is built on Leaflet rather than GL JS, the Leaflet guide shows how to keep it and still use vector tiles.

What it costs

MapLibre itself is free. Tiles are the only cost, and with ExpressMaps the first 100,000 map loads a month are free on every account, with paid plans from $29 a month for more. The Mapbox alternative page compares the numbers at different traffic levels.

Questions about a migration? Email support@expressmaps.com and we'll take a look at your code.

Back to List