All docschevron-rightHelpchevron-rightarrow-leftTroubleshootingchevron-rightTransition from Mapbox.js to Mapbox GL JS

Transition from Mapbox.js to Mapbox GL JS

If you’re using the Mapbox.js library in an existing web application, making the switch to Mapbox GL JS can lead to performance improvements that make the work required to transition worth the effort.

This guide highlights equivalent resources and transferrable resources that you can take advantage of when you switch from Mapbox.js to Mapbox GL JS. While every use case is unique, this document will give you a good overview of the kind of work that will be necessary to make this transition.

Here are the important differences between these two libraries:

Mapbox.js

  • No longer in active development.
  • Supports raster tiles.
  • Map tiles are generated by the server.
  • Map data and styles cannot be changed dynamically in the browser.
  • Only map overlays can be styled dynamically.

Mapbox GL JS

  • In active development — we are adding new features, improving existing features, and fixing bugs.
  • Supports raster tiles and vector tiles.
  • Maps are rendered client-side by the browser.
  • Map data, styles, and overlays can be changed dynamically.

Equivalent resources

You probably want to recreate your app's original functionality as closely as possible when you transition to Mapbox GL JS.

Below is a list of common Leaflet and Mapbox.js resources and their Mapbox GL JS equivalents to help you choose which tools to use as you switch libraries.

Initialize a map

Constructing a new map object in Mapbox GL JS involves many of the same pieces of information that are needed to initialize a map in Mapbox.js. You need your Mapbox access token, a center point (an array of coordinates), a zoom level (a number between 0 and 22), and an HTML element in which to place the map (specified by referencing the HTML element's id).

Both Mapbox.js and Mapbox GL JS also allow you to specify the style of the map. How the style is specified is the biggest difference you will see when initializing your map. Mapbox.js expects a tileset ID, which references a tileset. Mapbox GL JS expects a style URL, which refers to a style.json file (a JSON object that conforms to the Mapbox Style Specification and specifies what data to use and how to style that data). It is not possible to convert a tileset to style JSON.

Refer to the initialization syntax below to see the differences in action.

Mapbox.js

In Mapbox.js, you can initialize a new map with the following JavaScript:

const map = L.mapbox
  .map('map', 'mapbox.streets') // HTML container ID, Mapbox tileset
  .setView([40, -74.5], 9); // starting coordinates as [lat, lng], zoom level

The L.mapbox.map method, inherited from Leaflet L.map, references map, the HTML container ID for the map. It uses the .setView method to set the map view’s starting position in [latitude,longitude] format as well as the initial zoom level. While Mapbox.js uses [latitude, longitude] coordinate order, Mapbox GL JS uses [longitude, latitude] order. It also references mapbox://styles/mapbox/streets-v12, a Mapbox map style added as a styleLayer.

The map you see in your browser is composed of raster tiles. It is essentially a set of images that are arranged to display the whole world (at low zoom levels) or the area you are viewing (at higher zoom levels).

Mapbox GL JS

In Mapbox GL JS, you can initialize a new map with the following JavaScript:

const map = new mapboxgl.Map({
  container: 'map', // HTML container ID
  style: 'mapbox://styles/mapbox/streets-v12', // style URL
  center: [-21.9270884, 64.1436456], // starting position as [lng, lat]
  zoom: 13
});

The new mapboxgl.Map method references map, which again is the ID of the HTML container for the map. It also references the style URL for Mapbox Streets v9, a default Mapbox style. That style URL refers to Mapbox Streets v9's style.json file for information on how to style the data on the map. Finally, it sets the map's [longitude, latitude] starting position and the map's initial zoom level. Remember that Mapbox GL JS uses [longitude, latitude] coordinate format, while Mapbox.js uses [latitude, longitude] format.

The map you see in your browser is rendered dynamically by combining vector tiles with the style.json file of the style that was referenced in the initialization code.

Add a marker

The way that markers are added to a map in Mapbox GL JS is different than the way they are added in Mapbox.js. Mapbox.js allows you to use markers that are styled using simplestyle-spec to set the icon and color of the marker. With Mapbox GL JS, you do not use simplestyle to style markers. Instead, you can use the default marker style, or you can specify a background image for the marker div using CSS.

Mapbox.js

The Mapbox.js L.mapbox.marker.icon method, which inherits from L.Marker in Leaflet, lets you add a marker to a map and style it in the same step. The resulting marker is an actual image on top of the map.

L.marker([37.9, -77], {
  // [lat, lng] coordinates to place the marker at
  icon: L.mapbox.marker.icon({
    'marker-size': 'large', // specify the size of the marker
    'marker-symbol': 'bus', // specify the symbol to use in the marker
    'marker-color': '#fa0' // specify the color of the marker
  })
}).addTo(map); // add the marker to the map

Mapbox GL JS

The Mapbox GL JS new maboxgl.Marker.addTo method attaches the new marker image to the map as a DOM element. The default Mapbox marker is a light blue, droplet-shaped SVG marker. Since this default marker is a DOM element, you can override its styling with CSS if you choose to. (This technique is demonstrated in the Add custom icons with markers example.)

const marker = new mapboxgl.Marker()
  .setLngLat([30.5, 50.5]) // [lng, lat] coordinates to place the marker at
  .addTo(map); // add the marker to the map

This method works well for adding individual markers to a map. If you are using a lot of markers for point data, adding the data as symbol or circle layers provides better performance. But if you add the data to your map using map.addLayer, these new circle or symbol layers are specified in the style.json file and are not DOM elements.

Add a layer

One major difference between Mapbox.js and Mapbox GL JS is how these libraries treat feature layers. This has a big impact on how you will reference and use layers in your maps.

Mapbox.js

In Mapbox.js, a new layer can be added to a map with the following JavaScript:

const featureLayer = L.mapbox.featureLayer('mapbox.dc-markers').addTo(map);

The L.mapbox.featureLayer method, which is inherited from Leaflet’s L.FeatureGroup method, allows you to add a new layer to your map. The source can be GeoJSON, or it can be a URL pointing to a tileset or map style. The new layer is added to your map as a DOM element.

If you are using a GeoJSON source with Mapbox.js, you may be styling features using simplestyle. While you can't style features in Mapbox GL JS layers using simplestyle, you can repurpose the simplestyle-related properties in your GeoJSON to style features with data-driven styling in Mapbox GL JS.

Mapbox GL JS

In Mapbox GL JS, each layer provides rules about how the renderer will draw certain data in the browser. The renderer uses these layers to draw the map on the screen.

Every time you add a layer to a Mapbox GL JS map, you need to specify both a source and a layer:

  1. The source determines the geometry and will include any data properties (such as the name of a point or the rank of points of interest).
  2. The layer properties influences the appearance of the layer. This includes the type of layer (circle, symbol, fill, etc.), any paint or layout properties to specify the appearance of features, and the source (the geometries that these styles should be applied to).

This makes adding a layer is a two-step process: first adding the source data with the map.addSource method, then rendering the layer properties on the map with the map.addLayer method.

map.addSource('single-point', {
  type: 'geojson', // specify the kind of data being added
  data: {
    type: 'FeatureCollection',
    features: []
  }
});

map.addLayer({
  id: 'point', // the layer's ID
  source: 'single-point',
  type: 'circle', // the layer type
  paint: {
    'circle-radius': 10,
    'circle-color': '#007cbf'
  }
});
book
NOTE

The process of specifying a source and then adding a layer can also be done in one step by specifying a source within the map.addLayer method.

In Mapbox GL JS, new layers are added to the top of the style by default. You can also use a layer ID to specify a layer for the new layer to go on top of using addLayer's optional before parameter. This is not possible with Mapbox.js because the rendered map is a flat picture for which you cannot influence the order of the layers.

Transferable resources

Moving from Mapbox.js to Mapbox GL JS will necessarily mean that you will need to recreate your maps using the new framework. Most developers, though, find that many of the resources that they used with Mapbox.js can also be used with Mapbox GL JS with little or no modification.

ResourceTransferable?Notes
Default Mapbox styleIf you use a Default Mapbox style, you can update to the Mapbox GL JS version of that style. For example, if you used the Mapbox Classic Streets style with Mapbox.js, you could use Mapbox Streets v9 in your Mapbox GL JS app.
Custom dataIf you use custom data in Mapbox.js or Leaflet, it can probably be repurposed in Mapbox GL JS. For more information about using data sources in Mapbox GL JS, see the Mapbox Style Specification.
Custom markersIn Mapbox GL JS, markers are rendered by the GPU, not the browser, so any images you want to use as markers have to be loaded into a sprite and referenced in your map’s style JSON. You can add custom markers to a sprite in Mapbox Studio.

In a few cases, there are Leaflet or Mapbox.js features without exact equivalents in Mapbox GL JS. Our support staff can help you determine how to create the effect you’re trying to achieve, so contact us if you have questions.

Learn more about using Mapbox GL JS

To learn more about Mapbox GL JS and how to use it, explore the following resources: