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 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.

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. 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.

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 static object. This object has a single method createClass that the template code is passed to.

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 object specification.

Note. The API supports the base syntax for the Twig/Django Templates languages.
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>{{ }}</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 and later extracted by key.

var myBalloonContentLayoutClass = ymaps.templateLayoutFactory.createClass(...);'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 %}.

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. In the contour description for a shape, coordinates are given relative to the geo object's anchor point.
var myIconContentLayout = ymaps.templateLayoutFactory.createClass('<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 that illustrates working with hotspots when defining a layout for geo objects.