Legacy
Mapbox.js is no longer in active development. To learn more about our newer mapping tools see Mapbox GL JS.
TileLayer
Used to load and display tile layers on the map, implements ILayer interface.
Usage example
L.tileLayer('http://{s}.tile.osm.org/{z}/{x}/{y}.png?{foo}', {foo: 'bar'}).addTo(map);
Creation
Factory | Description |
---|---|
L.tileLayer(
|
Instantiates a tile layer object given a URL template and optionally an options object. |
URL template
A string of the following form:
'http://{s}.somedomain.com/blabla/{z}/{x}/{y}.png'
{s}
means one of the available subdomains (used sequentially to help with browser parallel requests per domain limitation; subdomain values are specified in options; a
, b
or c
by default, can be omitted), {z}
— zoom level, {x}
and {y}
— tile coordinates.
You can use custom keys in the template, which will be evaluated from TileLayer options, like this:
L.tileLayer('http://{s}.somedomain.com/{foo}/{z}/{x}/{y}.png', {foo: 'bar'});
Options
Option | Type | Default | Description |
---|---|---|---|
minZoom |
Number |
0 |
Minimum zoom number. |
maxZoom |
Number |
18 |
Maximum zoom number. |
maxNativeZoom |
Number |
null |
Maximum zoom number the tiles source has available. If it is specified, the tiles on all zoom levels higher than maxNativeZoom will be loaded from maxZoom level and auto-scaled. |
tileSize |
Number |
256 |
Tile size (width and height in pixels, assuming tiles are square). |
subdomains |
String or String[] |
'abc' |
Subdomains of the tile service. Can be passed in the form of one string (where each letter is a subdomain name) or an array of strings. |
errorTileUrl |
String |
'' |
URL to the tile image to show in place of the tile that failed to load. |
attribution |
String |
'' |
e.g. "© Mapbox" — the string used by the attribution control, describes the layer data. |
tms |
Boolean |
false |
If true , inverses Y axis numbering for tiles (turn this on for TMS services). |
continuousWorld |
Boolean |
false |
If set to true , the tile coordinates won't be wrapped by world width (-180 to 180 longitude) or clamped to lie within world height (-90 to 90). Use this if you use Leaflet for maps that don't reflect the real world (e.g. game, indoor or photo maps). |
noWrap |
Boolean |
false |
If set to true , the tiles just won't load outside the world width (-180 to 180 longitude) instead of repeating. |
zoomOffset |
Number |
0 |
The zoom number used in tile URLs will be offset with this value. |
zoomReverse |
Boolean |
false |
If set to true , the zoom number used in tile URLs will be reversed (maxZoom - zoom instead of zoom ) |
opacity |
Number |
1.0 |
The opacity of the tile layer. |
zIndex |
Number |
null |
The explicit zIndex of the tile layer. Not set by default. |
unloadInvisibleTiles |
Boolean |
depends | If true , all the tiles that are not visible after panning are removed (for better performance). true by default on mobile WebKit, otherwise false . |
updateWhenIdle |
Boolean |
depends | If false , new tiles are loaded during panning, otherwise only after it (for better performance). true by default on mobile WebKit, otherwise false . |
detectRetina |
|
false |
If true and user is on a retina display, it will request four tiles of half the specified size and a bigger zoom level in place of one to utilize the high resolution. |
reuseTiles |
|
false |
If true , all the tiles that are not visible after panning are placed in a reuse queue from which they will be fetched when new tiles become visible (as opposed to dynamically creating new ones). This will in theory keep memory usage low and eliminate the need for reserving new memory whenever a new tile is needed. |
bounds |
LatLngBounds |
null |
When this option is set, the TileLayer only loads tiles that are in the given geographical bounds. |
Events
You can subscribe to the following events using these methods.
Event | Data | Description |
---|---|---|
loading |
Event |
Fired when the tile layer starts loading tiles. |
load |
Event |
Fired when the tile layer loaded all visible tiles. |
tileloadstart |
TileEvent |
Fired when a tile is requested and starts loading. |
tileload |
TileEvent |
Fired when a tile loads. |
tileunload |
TileEvent |
Fired when a tile is removed (e.g. when you have unloadInvisibleTiles on). |
Methods
Method | Returns | Description |
---|---|---|
addTo(
|
this |
Adds the layer to the map. |
bringToFront() |
this |
Brings the tile layer to the top of all tile layers. |
bringToBack() |
this |
Brings the tile layer to the bottom of all tile layers. |
setOpacity(
|
this |
Changes the opacity of the tile layer. |
setZIndex(
|
this |
Sets the zIndex of the tile layer. |
redraw() |
this |
Causes the layer to clear all the tiles and request them again. |
setUrl(
|
this |
Updates the layer's URL template and redraws it. |
getContainer()
|
HTMLElement |
Returns the HTML element that contains the tiles for this layer. |