Announcing MapBox.js 1.0 with Leaflet

April 18 2013 by Tom MacWright

MapBox.js is now version 1.0 and we are joining forces with Leaflet, one of the most established and robust open source mapping libraries. Embedding maps in web applications with MapBox.js is now even easier, and you can tap into powerful Leaflet features and multi-platform compatibility. Specifically, one of the most frequently requested capabilities is native vector support – allowing for seamless combination of tile and vector data like in this example:

Vector overlay on MapBox map using MapBox.js 1.0 - view map and code

At the same time MapBox.js 1.0 continues to support simple convenience functions that make getting started with MapBox so easy:

// Load map "map-zr0njcqy" from MapBox account "examples".
var map ='map', '').setView([0, 0], 2);

Simple example of embedding a MapBox map with MapBox.js 1.0 - view code

Starting today you can use MapBox.js 1.0 by including a few lines of code in your application. Read on for more details on the release here or head directly to our MapBox.js documentation to get started coding.


MapBox.js is now a Leaflet plugin, which means that our hosted library includes a fresh version of Leaflet as well as code that make it easy to integrate with MapBox tiles and services. The plugin provides a smart map object,, that extends L.Map, as well as types for MapBox layers, controls, and utilities. As a Leaflet plugin, MapBox.js can integrate with any other Leaflet code - plugins, default layers, and more.

Straightforward API

MapBox.js 1.0’s API removes stumbling blocks for new users. Following Leaflet’s convention we’re replacing ‘magic methods’ like url() with more straightforward setURL(url) and getURL() methods. When appropriate, it checks that arguments are reasonable rather than throwing cryptic errors.

// v0
markersLayer.filter(function(f) { return; });
var filter = markersLayer.filter();

// v1
markersLayer.setFilter(function(f) { return; });
var filter = markersLayer.getFilter();

The version 0.6.7 API for managing MapBox’s fast UTFGrid-based interactivity and automatic settings through TileJSON was too difficult and error prone. To make this clearer, automatically updates when layers update, and controls like L.Control.Attribution will automatically show the attribution settings of new layers.


MapBox.js Examples are a great way to get started with MapBox.js quickly - find an example that does almost what you need, copy the code, modify it, and go. We’ve ported over 20 of the existing 0.6.x examples to 1.0 and will be continuously adding more to make it easier to understand and get started with the new code. The examples demonstrate everything from support for Retina tiles to WMS and polylines.

Of course, there are great Leaflet Tutorials that apply 100% to MapBox.js 1.0.

Available in Leaflet: Vector Layers

As mentioned earlier, you can now use dynamic vector features, like driving routes, polygons, and complete GeoJSON files in MapBox.js. This is implemented across platforms, backed by Leaflet’s tested implementation in HTML5 Canvas, SVG, and VML. We’re aiming for full browser support, ranging from modern desktop browsers like Chrome, Safari and Firefox to mobile browsers and Internet Explorer 7 - 10.

Leaflet’s vector layer features can complement TileMill’s deep styling control and fast raster output by providing a more dynamic, interactive layer for lightweight features.

Ecosystem of Leaflet Plugins

One of the biggest wins of switching to Leaflet as a basic map library is the availability of many map plugins. In the process of writing this API, we wrote several, including a fullscreen control and a point-in-polygon operation, and helped to improve others, like Michael Evans’s Leaflet.hash.

This open-source plugin community promises to make maps more extensible and flexible without weighing down the core Leaflet code.

The Leaflet marker cluster plugin is just one example of the many great Leaflet plugins now compatible with MapBox.js (click to see interactive version).

Tested & Supported

This release of MapBox.js is continuously tested with Travis CI and has a 115-part test suite. We’re aggressively testing IE8+, mobile devices, and modern browsers. As a Leaflet plugin, MapBox.js also benefits from the thousands of developers testing Leaflet, reporting bugs, and providing patches, and by the coverage provided by Leaflet’s own test suite. Thanks to John’s work in Mocha, these tests run quickly and easily.

MapBox.js 0.6.x Support

Existing apps linking to earlier MapBox.js versions will continue to work - every release of MapBox.js has a unique, versioned URL that is never updated or removed.

We’re planning on pulling in many fixes into a version 0.6.8 release that addresses bugs in Internet Explorer and Android, and will continue to support deployments using the prior API releases.

Open Source

As always, MapBox.js is an open source project on GitHub under an open license. This means you can fork it, download it, or learn from its design.