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

# Layouts and templates

The appearance of any displayed elements (balloon, hint, placemark, and others) is defined using _layouts_. The layout is an object that implements the [ILayout](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayout.md) interface and generates code that is responsible for the final representation of the object. Layout can change a document's DOM tree.

To change or set the appearance of an object being displayed, you must change or set the layout associated with it. Objects are associated with their layouts using the corresponding options.

```javascript
var myPlacemark = new ymaps.Placemark(
    [55.8, 37.6],
    {},
    {balloonContentLayout: MyBalloonContentLayoutClass}
    // MyBalloonContentLayoutClass — balloon layout class.
);
```

In contrast to options, which only allow for changing certain display parameters of an element, the layout allows to create any desired representation of it.

{% note info %}

Implementing a custom layout «from scratch» based on the `ILayout` interface is a relatively labor-intensive task, which is outside the scope of this guide. However, the sandbox has a sample that demonstrates an implementation of this task.

{% endnote %}

The API provides a convenient mechanism for generating layouts based on _templates_.

A template is HTML code that can include substitutions. To create layouts using the template language, a layout factory is provided — the [templateLayoutFactory](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/templateLayoutFactory.md) static object. This object has a single method [createClass](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/templateLayoutFactory.md#.createClass) that the template code is passed to.

```javascript
var MyBalloonContentLayoutClass = ymaps.templateLayoutFactory.createClass(
    '<div class="my-layout"><h3>Layout</h3><p>Created from a template.</p></div>' 
);
```

It is often necessary to use an object's data in its associated layout. For example, putting a placemark's name in its balloon.

Templates have access to certain fields in the parent object. In most cases, values are available for the fields `data` (or `properties`), `options`, and `state`. The values of these fields can be used in so-called substitutions. The possible types of substitutions are described in the [templateLayoutFactory](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/templateLayoutFactory.md) object specification.

{% note info %}

The API supports the base syntax for the Twig/Django Templates languages.

{% endnote %}

```javascript
var myPlacemark = new ymaps.Placemark(
    [55.8, 37.6],
    {
        name: 'Moscow',
        description: 'Capital. Lots of people.',
        metro: true
    },
    {balloonContentLayout: MyBalloonContentLayoutClass}
);
var MyBalloonContentLayoutClass = ymaps.templateLayoutFactory.createClass(
    '<h3>{{ properties.name }}</h3>' +
    '<p>Description: {{ properties.description }}</p>' +
    '<p>Population: {{ properties.population|default:"unknown" }}</p>' +
    '<p>Metropolitan: {% if properties.metro %}yes{% else %}no{% endif %}</p>'
);
```

Layouts can be placed in the special storage [{#T}layout.storage.md]](../../ref/reference/layout.storage.md) and later extracted by key.

```javascript
var myBalloonContentLayoutClass = ymaps.templateLayoutFactory.createClass(...);
ymaps.layout.storage.add('my#simplestBCLayout', MyBalloonContentLayoutClass);
var myPlacemark = new ymaps.Placemark(
    ...
    {balloonContentLayout:  'my#simplestBCLayout'}
);
```

Templates can include previously defined layouts. The examples that are provided redefine the balloon content layout, which originally includes three layouts: for the header, body, and footer.

To include a layout in a template, substitutions are used in the format `{% include 'key to the layout in storage' %}` and `{% include options.optionName %}`.

```javascript
var MyBalloonContentLayoutClass = ymaps.templateLayoutFactory.createClass(
    '{% include options.balloonContentLayout %}<p>...</p>{% include 'my#simplestBCLayout' %}' 
);
```

## Interactivity of geo objects

When adding geo objects to the map, their corresponding DOM elements are placed under the layer where subscribing to DOM events is implemented. This means that events of the map's geo objects are not tracked on the DOM level.

Interactivity of geo objects is implemented using hotspots, the essence of which consists in the following. The representation of each geo object is set as a basic geometric shape: a circle, rectangle, or polygon. These shapes, or hotspots, determine which parts of the map will be interactive. When a DOM event occurs at some point on the map, a check is performed to see whether this point falls on the hotspot.

For geo objects with the standard layout, hotspots are defined automatically. If a geo object has a custom layout defined, you must set its hotspot using the iconShape option. In its fields, specify the type of geometry that the hotspot accepts, as well as the description of its contour. For example, for a circle this is the coordinates of its center and the length of the radius in pixels.

{% note info %}

In the contour description for a shape, coordinates are given relative to the geo object's anchor point.

{% endnote %}

```javascript
var myIconContentLayout = ymaps.templateLayoutFactory.createClass('<div
 class="square_layout"></div>');
var squarePlacemark = new ymaps.Placemark(
      [55.725118, 37.682145],
      {
        hintContent: 'Placemark with a rectangular layout'
      }, {
        iconLayout: myIconContentLayout,
        // Describing the hotspot shape
        // "Rectangle".
        iconShape: {type: 'Rectangle',
          // A rectangle is described as two points -
          // the upper-left and lower-right.
          coordinates: [[-25, -25], [25, 25]]}
      }
    );
```

The sandbox has a more detailed [sample](http://api.yandex.ru/maps/jsbox/2.1/placemark_shape) that illustrates working with hotspots when defining a layout for geo objects.