--- layout: api title: "v1.6.0 API: L.mapbox.tileLayer(id|url|tilejson, options)" categories: api version: v1.6.0 permalink: /api/v1.6.0/l-mapbox-tilelayer ---

## 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 `{{site.tileApi}}/v3/examples.map-0l53fhk2.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 one addition:

- `retinaVersion`, if provided, is an alternative value for the first argument to `L.mapbox.tileLayer` which, if retina is detected, is used instead.

If `detectRetina` is set to true and the map in question supports auto-scaling, then a scaled version will automatically be useful if retina is detected and you don't provide an explicit `retinaVersion` to be used.

Example:

    // the second argument is optional
    var layer = L.mapbox.tileLayer('examples.map-20v6611k');

    // you can also provide a full url to a TileJSON resource
    var layer = L.mapbox.tileLayer('{{site.tileApi}}/v3/examples.map-0l53fhk2.json');

    // if provided, you can support retina tiles
    var layer = L.mapbox.tileLayer('examples.map-20v6611k', {
        tileLayer: {
            detectRetina: true,
            // if retina is detected, this layer is used instead
            retinaVersion: 'examples.map-zswgei2n'
        }
    });

    // if this map supports auto-scaling, `detectRetina` will automatically
    // use scaled tiles when retina is detected.
    var layer = L.mapbox.tileLayer('examples.map-20v6611k', {
        tileLayer: {
            detectRetina: true,
        }
    });

Returns a `L.mapbox.tileLayer` object.

### tileLayer.getTileJSON()

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

Example:

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

Returns: the TileJSON object

### tileLayer.setFormat(format)

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'

Example:

    // Downsample tiles for faster loading times on slow
    // internet connections
    var layer = L.mapbox.tileLayer('examples.map-20v6611k', {
        format: 'jpg70'
    });

Returns: the layer object