--- layout: api title: "v1.6.1 API: L.mapbox.tileLayer(id|url|tilejson, options)" categories: api version: v1.6.1 permalink: /api/v1.6.1/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', {
        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', {
        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