Converting a project from Mapbox.js to Mapbox GL JS

For developers who have experience building web maps with Mapbox.js or Leaflet, switching old projects to use Mapbox GL JS can drastically improve the performance of your existing applications. Mapbox GL JS uses WebGL client-side rendering to display your maps, which results in faster loading, smoother transitions when zooming or panning, and greater flexibility to change map data and styles on the fly. These improvements make switching to Mapbox GL JS well worth the effort, so I recently converted Peter’sCourier demo from Mapbox.js to GL.

Here are some key tips to illustrate how you can make the switch with your projects!

Adding map layers and data

In the Courier demo, the pickup points for packages are stored as GeoJSON in the browser and constantly updated with new orders. In Mapbox.js, we added those points to the map using L.mapbox.featureLayer(), and with each update of the pickupPoints GeoJSON object we update the layer’s source using featureLayer().setGeoJSON():

varpickups=L.mapbox.featureLayer(pickupPoints).addTo(map);// when new pickups are addedpickups.setGeoJSON(pickupPoints);

In Mapbox GL JS, we first add a source to the map, and then create a new layer:

map.addSource('pickups',{type:'geojson',data:pickupPoints});map.addLayer({id:'pickups',source:'pickups',type:'symbol',layout:{'icon-image':'pickup'}});

When new data are added to the pickupPoints object, we update the new layer’s underlying source using setData() instead of updating the layer directly:

map.getSource('pickups').setData(pickupPoints);

Adding custom markers to Mapbox GL Maps

Because feature layers in Mapbox.js are DOM elements, it is possible to use any image file as a marker on the map. In Mapbox GL JS, however, markers are rendered by the GPU, not the browser, so any images you would like 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 - this handy guide walks you through the whole process. Alternatively, you can use spritezero, our open-source sprite generator to build your sprite from the command line, or on the fly in your application.

Animations in Mapbox GL JS

We can animate DOM elements using CSS, which is how Peter animated the line of the couriers' paths to their destinations in the original Courier demo. Since we cannot use DOM manipulation, we’ll use the same setData() method on our GeoJSON source that we used in the above pickupPoints example, but this time we’ll use it in conjunction with Turf and the JavaScript method window.requestAnimationFrame just like this example.

functionanimateCourier(route,destination){// set animation speed at 60x real timevarspeed=60;varduration=route.duration;varpath=turf.linestring(route.geometry.coordinates);vardistance=turf.lineDistance(path);// get starting time of the animationvarstart=performance.now();functionanimate(timestamp){varcurrent_time=timestamp-start;// if the animation has reached its destination, // move the courier to the destination and end the animation loopif((current_time*speed)/(duration*1000)>=1){map.getSource('courier').setData(destination)}else{// find the current distance the courier has traveled along the pathvarcurrent_distance=current_time*speed)/(duration*1000)*distance;varwaypoint=turf.along(path,current_distance,"kilometers");map.getSource('courier').setData(waypoint);// continue the animation looprequestAnimationFrame(animate);}}animate(start);}

To learn more about Mapbox GL JS and how you can implement your projects with it, check out our Mapbox GL JS Fundamentals guide, or take a look at some of the examples.