---
metadata:
  - name: generator
    content: Diplodoc Platform v5.39.1
alternate:
  - https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md
  - https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Layer.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/jsapi-v2-1/doc/en/llms.txt

# Layer

Extends [ILayer](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md), [IParentOnMap](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IParentOnMap.md), [IPositioningContext](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPositioningContext.md).

Tile layer. Allows to display a layer consisting of tiles on the map.

[Constructor](#constructor-summary) | [Fields](#properties-summary) | [Events](#events-summary) | [Methods](#methods-summary)

## Constructor {#constructor-summary}

```javascript
Layer(tileUrlTemplate[, options])
```

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`tileUrlTemplate`](#param-tileUrlTemplate)[*](*star) | — | Type: String\|Function

String template for the tile URL, or a function that generates the tile URL. For the string template, the following substitutions are supported:

- %c is replaced with `x=number[0]&y=number[1]&z=zoom level`.
- %x is replaced with number[0].
- %y is replaced with number[1].
- %z is replaced with the zoom level.
- %l is replaced with lang=language.
- %d or %d\|n is replaced with a number from 1 to n, depending on the tile number; n is the number of domains. Used for distributing the load over multiple domains. For n, specify a factor of two (2, 4, 16, and so on). If the template has %d, then n=4.

The template function receives three input parameters:

- tileNumber - Array of two numbers, the tile numbers on x and y.
- tileZoom - Zoom level.
- Returns a URL string. ||
|| [`options`](#param-options) | — | Type: Object

Options. ||
|| [`options.brightness`](#param-options.brightness) | 0.5 | Type: Number

Layer brightness. Specified as a number from 0 to 1. 0 corresponds to black, and 1 to white. ||
|| [`options.notFoundTile`](#param-options.notFoundTile) | null | Type: String\|null

Option that specifies the URL for downloading an image if the tile image didn't load. If the value is null, a standard tile is displayed with a text message. For transparent tiles, the notFoundTile option is not applied, and nothing is shown in place of tiles that didn't load. ||
|| [`options.pane`](#param-options.pane) | 'ground' | Type: [IPane](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPane.md)\|String

Pointer to the layer pane or key from [map.pane.Manager](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/map.pane.Manager.md). ||
|| [`options.projection`](#param-options.projection) | — | Type: Object

Layer projection. ||
|| [`options.tileSize`](#param-options.tileSize) | [256, 256] | Type: Number[]

Size of tiles on the layer. ||
|| [`options.tileTransparent`](#param-options.tileTransparent) | false | Type: Boolean

Flag showing whether layer tiles are transparent. ||
|| [`options.zIndex`](#param-options.zIndex) | constants.zIndex.layer | Type: Number

Z-index of the layer in the layers container. ||
|#

\* Mandatory parameter/option.

**Example:**

```javascript
// Adds an OSM layer to the map.
map.layers.add(new ymaps.Layer('http://tile.openstreetmap.org/%z/%x/%y.png', {
    projection: ymaps.projection.sphericalMercator
}));
map.copyrights.add('© OpenStreetMap contributors, CC-BY-SA');
```

## Fields {#properties-summary}

#|
|| **Name** | **Type** | **Description** ||
|| [events](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IEventEmitter.md#events) | [IEventManager](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IEventManager.md) | Event manager.

Inherited from [IEventEmitter](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IEventEmitter.md#events). ||
|| [options](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICustomizable.md#options) | [IOptionManager](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IOptionManager.md) | Options manager.

Inherited from [ICustomizable](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICustomizable.md#options). ||
|#

## Events {#events-summary}

#|
|| **Name** | **Description** ||
|| [brightnesschange](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#event-brightnesschange) | Layer brightness change event.

Inherited from [ILayer](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#event-brightnesschange). ||
|| [copyrightschange](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#event-copyrightschange) | Event for changes to available copyright information.

Inherited from [ILayer](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#event-copyrightschange). ||
|| [mapchange](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IParentOnMap.md#event-mapchange) | Map reference changed. Data fields: 
- oldMap - Old map.
- newMap - New map.

Inherited from [IParentOnMap](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IParentOnMap.md#event-mapchange). ||
|| [optionschange](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICustomizable.md#event-optionschange) | Change to the object options.

Inherited from [ICustomizable](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICustomizable.md#event-optionschange). ||
|| [parentchange](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChild.md#event-parentchange) | The parent object reference changed.

Data fields:

- oldParent - Old parent.
- newParent - New parent.

Inherited from [IChild](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChild.md#event-parentchange). ||
|| [tileloadchange](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#event-tileloadchange) | Tile upload status change event. Data fields: 
- readyTileNumber - Number of ready tiles. A tile is considered ready when it is downloaded and rendered. Type: Number.
- totalTileNumber - Total number of visible tiles. Type: Number.

Inherited from [ILayer](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#event-tileloadchange). ||
|| [zoomrangechange](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#event-zoomrangechange) | Event for changes to available information about the zoom level range.

Inherited from [ILayer](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#event-zoomrangechange). ||
|#

## Methods {#methods-summary}

#|
|| **Name** | **Returns** | **Description** ||
|| [clientPixelsToNumber](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#clientPixelsToNumber)([clientPixelPoint](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#clientPixelsToNumber-param-clientPixelPoint), [tileZoom](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#clientPixelsToNumber-param-tileZoom)) | Number[] | Returns the number of the tile that the specified point falls on for the specified tile zoom level. ||
|| [fromClientPixels](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPositioningContext.md#fromClientPixels)([clientPixelPoint](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPositioningContext.md#fromClientPixels-param-clientPixelPoint)) | Number[] | Converts client pixel coordinates to global coordinates.

Inherited from [IPositioningContext](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPositioningContext.md#fromClientPixels). ||
|| [getBrightness](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#getBrightness)() | Number | Optional method.

Inherited from [ILayer](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#getBrightness). ||
|| [getCopyrights](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#getCopyrights)([coords](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#getCopyrights-param-coords), [zoom](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#getCopyrights-param-zoom)) | [vow.Promise](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/vow.Promise.md) | Optional method. Requests information about copyrights at the specified point with the specified zoom.

Inherited from [ILayer](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#getCopyrights). ||
|| [getMap](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IParentOnMap.md#getMap)() | [Map](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Map.md) | Returns reference to the map.

Inherited from [IParentOnMap](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IParentOnMap.md#getMap). ||
|| [getPane](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#getPane)() | [IPane](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPane.md) | Returns the container that the layer is located in. ||
|| [getParent](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md#getParent)() | [IParentOnMap](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IParentOnMap.md)\|null | Returns link to the parent object, or null if the parent element was not set.

Inherited from [IChildOnMap](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md#getParent). ||
|| [getTileSize](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#getTileSize)([zoom](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#getTileSize-param-zoom)) | Number[] | Returns the horizontal and vertical tile dimensions for the specified zoom level. ||
|| [getTileStatus](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#getTileStatus)() | Object | Returns the total number of visible tiles and the number of ready tiles. A tile is considered ready when it is downloaded and rendered. ||
|| [getTileUrl](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#getTileUrl)([tileNumber](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#getTileUrl-param-tileNumber), [tileZoom](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#getTileUrl-param-tileZoom)) | String\|null | Returns the tile URL by its number and zoom level, or null if there is no data for the requested section. ||
|| [getTileUrlTemplate](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#getTileUrlTemplate)() | String\|Function | Returns string template for the tile URL, or a function that generates it. ||
|| [getZoom](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPositioningContext.md#getZoom)() | Number | Returns the current zoom level at which the positioning context works.

Inherited from [IPositioningContext](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPositioningContext.md#getZoom). ||
|| [getZoomRange](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#getZoomRange)([point](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#getZoomRange-param-point)) | [vow.Promise](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/vow.Promise.md) | Optional method. Checks the available range of zoom levels at the specified point. If there is data, the returned promise object will be resolved and will pass as a result an array of two numbers - the minimum and maximum zoom level available at the point. If there is no data, the promise is rejected with an error.

Inherited from [ILayer](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayer.md#getZoomRange). ||
|| [numberToClientBounds](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#numberToClientBounds)([tileNumber](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#numberToClientBounds-param-tileNumber), [tileZoom](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#numberToClientBounds-param-tileZoom)) | Number[][] | Converts the tile number and zoom level to the area occupied by the tile in client coordinates of the parent container. ||
|| [restrict](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#restrict)([number](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#restrict-param-number), [tileZoom](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#restrict-param-tileZoom)) | Integer[]\|null | Applies restrictions to the visible area for tiles (including map cycling on the x and y axes). ||
|| [setParent](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md#setParent)([parent](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md#setParent-param-parent)) | [IChildOnMap](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md) | Sets the parent object. If the null value is passed, the manager element will only be deleted from the current parent object.

Inherited from [IChildOnMap](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md#setParent). ||
|| [setTileUrlTemplate](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#setTileUrlTemplate)([tileUrlTemplate](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#setTileUrlTemplate-param-tileUrlTemplate))

**Name:** [toClientPixels](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPositioningContext.md#toClientPixels)([globalPixelPoint](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPositioningContext.md#toClientPixels-param-globalPixelPoint)) | Number[] | Converts global pixel coordinates to client coordinates.

Inherited from [IPositioningContext](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPositioningContext.md#toClientPixels). ||
|| [update](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Layer.md#update)() | Deletes the old tiles and requests new ones.||
|#

## Methods details {#method_detail}

### clientPixelsToNumber {#clientPixelsToNumber}

```javascript
{Number[]} clientPixelsToNumber(clientPixelPoint, tileZoom)
```

**Returns** the number of the tile that the specified point falls on for the specified tile zoom level.

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`clientPixelPoint`](#clientPixelsToNumber-param-clientPixelPoint)[*](*star) | — | Type: Number

A point in client pixel coordinates. ||
|| [`tileZoom`](#clientPixelsToNumber-param-tileZoom)[*](*star) | — | Type: Number

Tile zoom level. ||
|#

\* Mandatory parameter/option.

### getPane {#getPane}

```javascript
{IPane} getPane()
```

**Returns** the container that the layer is located in.

### getTileSize {#getTileSize}

```javascript
{Number[]} getTileSize(zoom)
```

**Returns** the horizontal and vertical tile dimensions for the specified zoom level.

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`zoom`](#getTileSize-param-zoom)[*](*star) | — | Type: Number

Zoom value. ||
|#

\* Mandatory parameter/option.

**Example:**

```javascript
// Show tiles for a larger zoom level,
// stretched to twice their size up to 512x512 pixels.
// For example, to reduce traffic.
var layer = new ymaps.Layer('', {
    projection: ymaps.projection.sphericalMercator
});
layer.getTileUrl = function (tileNumber, zoom) {
    return [
        'http://tile.openstreetmap.org',
        Math.max(zoom - 1, 0), tileNumber[0], tileNumber[1]
    ].join('/') + '.png';
}
layer.getTileSize = function (zoom) {
    if (zoom == 0) {
        return [256, 256];
    }
    return [512, 512];
}
map.copyrights.add('© OpenStreetMap contributors, CC-BY-SA');
```

### getTileStatus {#getTileStatus}

```javascript
{Object} getTileStatus()
```

Returns the total number of visible tiles and the number of ready tiles. A tile is considered ready when it is downloaded and rendered.

**Returns** object with following fields: 
- readyTileNumber - Number of ready tiles. Type: Number.
- totalTileNumber - Total number of tiles. Type: Number.

### getTileUrl {#getTileUrl}

```javascript
{String|null} getTileUrl(tileNumber, tileZoom)
```

**Returns** the tile URL by its number and zoom level, or null if there is no data for the requested section.

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`tileNumber`](#getTileUrl-param-tileNumber)[*](*star) | — | Type: ||
|| [`tileZoom`](#getTileUrl-param-tileZoom)[*](*star) | — | Type: ||
|#

\* Mandatory parameter/option.

**Example:**

```javascript
// Defines the function for generating the tile URL.
var layer = new ymaps.Layer('');
layer.getTileUrl = function (tileNumber, zoom) {
    return [
        'http://tile.openstreetmap.org',
        zoom, tileNumber[0], tileNumber[1]
    ].join('/') + '.png';
}
```

### getTileUrlTemplate {#getTileUrlTemplate}

```javascript
{String|Function} getTileUrlTemplate()
```

**Returns** string template for the tile URL, or a function that generates it.

### numberToClientBounds {#numberToClientBounds}

```javascript
{Number[][]} numberToClientBounds(tileNumber, tileZoom)
```

Converts the tile number and zoom level to the area occupied by the tile in client coordinates of the parent container.

**Returns** the area in client pixel coordinates.

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`tileNumber`](#numberToClientBounds-param-tileNumber)[*](*star) | — | Type: Integer[]

Tile number. ||
|| [`tileZoom`](#numberToClientBounds-param-tileZoom)[*](*star) | — | Type: Integer

Tile zoom level. ||
|#

\* Mandatory parameter/option.

### restrict {#restrict}

```javascript
{Integer[]|null} restrict(number, tileZoom)
```

Applies restrictions to the visible area for tiles (including map cycling on the x and y axes).

**Returns** the new tile number calculated with restrictions, or null if the tile is not in the visible area.

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`number`](#restrict-param-number)[*](*star) | — | Type: Integer[]

Tile number. ||
|| [`tileZoom`](#restrict-param-tileZoom)[*](*star) | — | Type: Integer

Tile zoom level. ||
|#

\* Mandatory parameter/option.

### setTileUrlTemplate {#setTileUrlTemplate}

```javascript
{} setTileUrlTemplate(tileUrlTemplate)
```

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`tileUrlTemplate`](#setTileUrlTemplate-param-tileUrlTemplate)[*](*star) | — | Type: String\|Function

String template for the tile URL, or a function that generates it. ||
|#

\* Mandatory parameter/option.

### update {#update}

```javascript
{} update()
```

Deletes the old tiles and requests new ones.

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`updateBounds`](#update-param-updateBounds)[*](*star) | — | Type: ||
|#

\* Mandatory parameter/option.

[*star]: Mandatory parameter/option.