Transition from Mapbox.js to Mapbox GL JS

Mapbox provides many tools to build maps into your website or web-based application, including Mapbox GL JS and Mapbox.js. Mapbox GL JS and Mapbox.js are both open source JavaScript libraries you can use to display your Mapbox maps, add interactivity, and customize the map experience in your application. There are some important differences between the two libraries, though, that will impact how you use them to build your apps.

Mapbox.js

  • No longer in active development
  • Supports raster tiles
  • Tiles are generated by the server
  • Map styles can’t be changed in the browser, but map overlays can be styled dynamically

Mapbox GL JS

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

If you’re using the Mapbox.js library, making the switch to Mapbox GL JS can lead to improvements with the performance of your existing applications. The advantages provided by Mapbox GL JS make the work required to switch from Mapbox.js to Mapbox GL JS worth the effort.

The purpose of this guide is to highlight equivalent resources and transferrable resources that Mapbox users can take advantage of when they 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.

Equivalent resources

When you transition from using Mapbox.js to using Mapbox GL JS, you will likely want to recreate your app’s original functionality as closely as possible. This means that you will need to take advantage of resources that allow you to have the same action or effect in Mapbox GL JS that you had when using Mapbox.js.

The following list of common Leaflet and Mapbox.js resources and their Mapbox GL JS equivalents will help you know 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 map 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:

var map = L.mapbox.map('map', 'mapbox.streets') // HTML container ID, Mapbox tileset
  .setView([40, -74.50], 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, and mapbox.streets, a default Mapbox raster tileset. It also uses the .setView method to set the map view’s starting position in [latitude,longitude] format as well as the initial zoom level. Keep in mind that while Mapbox.js uses [latitude, longitude] coordinate order, Mapbox GL JS uses [longitude, latitude] order.

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:

var map = new mapboxgl.Map({
  container: 'map', // HTML container ID
  style: 'mapbox://styles/mapbox/streets-v9', // 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. Keep in mind 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.)

var 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:

var 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 certain data should be drawn in the browser. The renderer uses these layers to actually 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'
  }
});

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.

Resource Transferable? Notes
Default Mapbox style If 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 data If 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 markers In 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.
Custom classic style Custom classic styles made with Mapbox Studio Classic cannot be used with Mapbox GL JS. Recreate your Classic style in Mapbox Studio to take advantage of Studio’s advanced styling features.

In a few cases, there are Leaflet or Mapbox.js features without exact equivalents in Mapbox GL JS. Our support staff can help you figure out how best 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, check out the following resources: