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.

L.mapbox.tileLayer(id|url|tilejson, options)

You can add a tiled layer to your map with L.mapbox.tileLayer(), a simple interface to layers from Mapbox and elsewhere.

Extends: L.TileLayer

Options Value Description
id or url or tilejson (required) string if id or url object if tilejson Value must be
  • An id string examples.map-foo
  • A URL to TileJSON, like https://api.mapbox.com/v3/mapbox.dark.json
  • A TileJSON object, from your own Javascript code
options object The second argument is optional. If provided, it is the same options as provided to L.TileLayer, with the following addition:


// the second argument is optional
var layer = L.mapbox.tileLayer('mapbox.streets');

// you can also provide a full url to a TileJSON resource
var layer = L.mapbox.tileLayer('https://api.mapbox.com/v3/mapbox.dark.json');

Returns a L.mapbox.tileLayer object.

Class: L.mapbox.TileLayer


Returns this layer's TileJSON object which determines its tile source, zoom bounds and other metadata.


var layer = L.mapbox.tileLayer('mapbox.streets')
    // since layers load asynchronously through AJAX, use the
    // `.on` function to listen for them to be loaded before
    // calling `getTileJSON()`
    .on('ready', function() {
        // get TileJSON data from the loaded layer
        var TileJSON = layer.getTileJSON();

Returns: the TileJSON object


Set the image format of tiles in this layer. You can use lower-quality tiles in order to load maps faster

Options Value Description
format string string an image format. valid options are: 'png', 'png32', 'png64', 'png128', 'png256', 'jpg70', 'jpg80', 'jpg90'


// Downsample tiles for faster loading times on slow
// internet connections
var layer = L.mapbox.tileLayer('mapbox.streets', {
    format: 'jpg70'

Live example of .setFormat in use

Returns: the layer object