Mapbox.js is no longer in active development. To learn more about our newer mapping tools see Mapbox GL JS.

You are viewing an older version of Mapbox.js. Check out v3.3.1 for the latest.

Upgrading from Mapbox.js v1

In a few cases, you may need to make changes to code written for Mapbox.js 1.x versions in order to work with Mapbox.js 2.x.

  • Mapbox.js 2.x uses version 4 of the Mapbox web services API, which requires API access tokens. You must supply an access token to Mapbox.js; see API access tokens for details.

  • The markerLayer alias has been removed from L.mapbox.map. Use featureLayer instead. For example, replace

    map.markerLayer.setFilter(function(f) { ... });


    map.featureLayer.setFilter(function(f) { ... });
  • L.mapbox.geocoder and L.mapbox.geocoderControl no longer accept arbitrary map IDs. Instead you must provide a predefined geocoder index ID (or the ID of a custom geocoder index). For instance, replace




    See the geocoding API documentation for a complete list of predefined geocoding indexes.

  • The format for L.mapbox.geocoder and L.mapbox.geocoderControl results have changed. Results are now provided in GeoJSON format. If your code uses L.mapbox.geocoder or the found, select, or autoselect events from L.mapbox.geocoderControl, it may need to be updated to expect the format documented in those classes.

  • L.mapbox.config.HTTP_URLS and L.mapbox.config.HTTPS_URLS have been replaced with L.mapbox.config.HTTP_URL and L.mapbox.config.HTTPS_URL, which expect to be assigned a single URL rather than an array of URLs. For example, replace

    L.mapbox.config.HTTP_URLS = ["http://example.com/"];


    L.mapbox.config.HTTP_URL = "http://example.com/";
  • L.mapbox.tileLayer no longer supports detectRetina, retinaVersion, or autoscale options. Instead, retina tiles are always automatically used when available.

  • L.mapbox.geocoder no longer has setURL, setID, and setTileJSON methods. Instead of resetting the URL or ID, construct a new instance with the desired URL or ID. Instead of setting TileJSON, construct an instance from the geocoding URL in the TileJSON.