Mapbox GL JS vs. Mapbox.js

From the Mapbox glossary, Mapbox.js > Mapbox.js is a JavaScript library that allows you to add an your interactive map to your website. It is a plugin for Leaflet, and it is an open source library that’s free to use.

and Mapbox GL JS >Mapbox GL JS is a JavaScript library that uses Mapbox GL to render interactive maps. It’s an open source library that’s free to use. You can add a Mapbox style or a custom style created with Mapbox Studio to your Mapbox GL JS application.

and from this answer > Mapbox Styles are for use with Mapbox GL and the native iOS and Android SDK's. You can't use them with classic Mapbox JS. Mapbox JS supports raster tiles, you can't style those. They're just images. Mapbox GL and the native SDK's (can) use vector tiles and those are stylable.

I believe I can use mapbox.js as a replacement to the leaflet css and js sources, but can I do the same with mapbox-gl.js?
What other differences exist between the two libraries?

As far as i know, Mapbox GL JS is going to be the replacement for the current Mapbox JS which uses Leaflet in the background. A lot of things Leaflet does, GL can do too and more. But not everything. The same goes vice versa. GL can do things Leaflet can't do. The big thing in GL is that it's built around vector tiles using WebGL. From the introduction article:

> Announcing Mapbox GL JS — a fast and powerful new system for web maps. Mapbox GL JS is a client-side renderer, so it uses JavaScript and WebGL to dynamically draw data with the speed and smoothness of a video game. Instead of fixing styles and zoom levels at the server level, Mapbox GL puts power in JavaScript, allowing for dynamic styling and freeform interactivity. Vector maps are the next evolution, and we're excited to see what developers build with this framework.

If you really want a side by side comparison of the two, I'm sorry there is none as far as I know. There are too many things to mention/consider when making a comparison so it's best you do such a thing by yourself based upon your own requirements. A good start would be comparing the examples for each framework because it gives a good idea of what both can do:

• https://www.mapbox.com/mapbox-gl-js/examples/
• https://www.mapbox.com/mapbox.js/example/v1.0.0/

After that you could compare their API's:

• https://www.mapbox.com/mapbox-gl-js/api/
• https://www.mapbox.com/mapbox.js/api/v2.2.4/

One thing to keep in mind is that GL is brand spanking new and as we developers all know that comes with a price. Some kinks haven't been ironed out. As for Leaflet, it's very mature, widely used and very well tested/proven. If you'd like to take a peek at what problems there are currently with GL you could take a look at the issues over at Github, in the repository:

• https://github.com/mapbox/mapbox-gl-js/issues

Hope that helps, good luck!

iH8's answer is great, to add a bit more detail:

For base maps, Mapbox.js displays raster tiles (PNG & JPEG) files, and displays them using HTML & CSS. Mapbox GL JS displays vector tiles (fancy protocol buffers) and displays them using WebGL. It can also display raster tiles, but that's not the focus.

Both Mapbox.js and Mapbox GL JS support overlays like GeoJSON layers and markers. Both are open source, with similar licenses and a few shared contributors.

The styles for Mapbox.js layers are stored on servers and rendered with server technology. The styles for Mapbox GL JS are rendered dynamically in a browser, so they can be changed in realtime.

Leaflet has more broad browser support, at the cost of a few things that some browsers can't support, like map tilt and rotation. Mapbox GL supports browsers that support WebGL and performs best on newer computers. It has a native version, called Mapbox GL Native, that performs really well on all mobile phones.

Despite the names, you can use Leaflet with Mapbox and Mapbox.js and Mapbox GL with non-Mapbox styles.

I'm currently working on switching a complex Leaflet based map system over to Mapbox GL and I'd say that one notable difference I've found is in the draw tools and handling of GeoJSON layers. Leaflet has a suite of draw tools that include non-standard GeoJSON like markers, rectangles and circles. The developers of Mapbox GL made a decision to focus on native GeoJSON, which means there's no out of the box support for drawing/rendering circles and rectangles (e.g. there's nothing like L.Circle in Mapbox GL); there is a marker but styling it to look like a traditional Leaflet marker requires creating your own sprites or using an SVG. All of these things are still possible, but they take a little more set up on the part of the developer than they did in Leaflet.

Additionally, most of the Mapbox GL layers are rendered as canvas elements. This means that, unlike Leaflet, there are no HTML elements associated with your various layers. This makes it harder to target the elements with CSS if needed. One exception I've found here is markers which are rendered as separate HTML elements.

All of that being said, I've been able to almost fully replicate the existing draw tools and rendering styles with some small differences. If you need highly customized draw tools, Mapbox GL may be frustrating for you.

Browser support has been mentioned as a potential issue as well. Any browser that supports WebGL can run Mapbox GL. This includes all major browsers. The only significant browser set we saw that didn't support Mapbox GL was IE10 or older, but our analytics indicated that almost none of our users still used these browsers so we officially dropped support for them. Your mileage may vary obviously.

Overall though, I'm happy with the switch because I think Mapbox GL is easier to work with and provides a better user experience.

Generally Leafletjs and Mapbox.js are the same, but with Mapbox.js having plugins and extensions which wrap Leaflet and tie into Mapbox's services (eg directions). Similar plugins and features exist from other companies or products and Leaflet can use them in addition to, or instead of Mapbox. The Leaflet-based libraries typically have better legacy browser support, use raster tiles, etc. That said features are being added that incorporate modern features like vector tiles (pbf, mvt, etc) and various renderers (including webgl).

Mapbox-gl-js and the native variant mapbox-gl are open-source libraries that are high-performance, highly optimized around vector tiles (pbf, mvt) and webgl for rendering into a canvas element (for the -js variant). It is relatively new so some things that are easy with Leaflet might be different or challenging (as of April 2016), that said they're very similar and work quite well, including on mobile devices (from the past few years, eg iphone 5s). An example of a random quirk is that Hebrew labels in Israel, which read right-to-left, are backward and look like nonsense (it's an open issue being addressed).

If dropping older browser support is okay going the Mapbox-gl(-js) route can be a fine choice. In my limited experience (working with it a few months) it has the best user+developer experience overall and Mapbox has been consistent in their engineering/output. I have less experience with their paid services and it's unclear how tightly coupled their libraries will be to these services. For a mobile project I moved to mapbox-gl-js after looking at Google Maps, Leaflet v0.7 and v1 and it seems to have been a good decision.

I started using Mapbox-gl-js with prior Leaflet experience and proficiency in HTML/CSS/JS and found the primer and examples both helpful in understanding technical details. Including how the map is styled with JSON (not CSS). Also take a close look at the terms of service, this was an important positive differentiator especially compared with Google. Mapbox's services don't have the most robust coverage outside the USA so be sure to give this some review as well (in my experience another provider is typically available, so this doesn't necessarily affect the decision to adopt the libraries, they're just very tightly coupled to Mapbox features or standards).

We've been using Mapbox-gl-js for over a year after transitioning from Leafletjs. We switched because we wanted to take advantage of the vector tiles feature. Overall we've liked Mapbox-gl-js though we've have run into a couple of gotchas.

We've run into some memory issues with Mapbox-gl-js (due to the fact WebGL is a hog), especially with some of our vector tiles. You definitely have to be careful about how much data is stored within the tiles themselves.

The other issue we're running into is working with government agencies and them having PCs that are locked down for security to the nth degree, such as turning off WebGL support at the OS level (they like to lock everything down no matter what). This is a killer because Mapbox-gl-js doesn't work without WebGL and getting a government agency to change a security policy is not an easy or quick thing to do. Unfortunately there doesn't seem to be any sort of easy fallback if a user doesn't have WebGL. We're still looking into the best solution for this problem.

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’s Courier demo from Mapbox.js to GL

Mapbox.js is deprecated, use Mapbox GL JS as stated on their website :

> 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

The article also contains examples of differences and similarities between the two.

If you're planning on rendering more than 10 maps per page I'd recommend not using mapbox-gl. Mapbox-gl uses WebGl to dynamically draw maps. Although all modern browsers have support for WebGl we've ran into problems when opening too many WebGl contexts. Too many is subjective and dependent on exactly which browser your client is using. The number of contexts also seems to be tab independent so if your client has a tab open that is already using "too many" contexts your maps might not render as a consequence.

See below for a couple of linked issues:

https://github.com/mapbox/mapbox-gl-js/issues/6312

https://github.com/mapbox/mapbox-gl-js/issues/7332

I've never used mapbox.js or leaflet for that matter, but for pages that require 10 or more maps I can definitely recommend not using mapbox-gl.