2.1.62 (current version)
2.1.64 (release candidate)

Developing the frontend

Creating a manager

The object manager is created using the RemoteObjectManager class. Its constructor can be passed the following parameters:

  • urlTemplate — Template for the data URL (mandatory parameter).

    More about templates

    Using templates lets the manager automatically generate the appropriate URL for each tile (or for a particular area). For example, let's assume the template for the data URL looks like this:


    When forming a request, the manager performs substitution: in place of %t it substitutes the numbers of the upper-left and lower-right tiles of the requested area. So, for example, an area with the corner tiles [1,1] and [5,5] will have a data URL that looks like this:


  • Manager options.
var remoteObjectManager = new ymaps.RemoteObjectManager('',
        // Cluster options are set with the 'cluster' prefix.
        clusterHasBalloon: false,
        // Object options are set with the geoObject prefix.
        geoObjectOpenBalloonOnClick: false

In order for the manager to start loading objects from the server, it must be added to the collection of map objects.


After being added to the map, the manager starts sending requests for data for the visible map area.

The manager puts loaded objects in the objectManager.ObjectCollection collection, which is linked to from objectManager.objects.

Setting up interaction between the manager and server

Most of the manager options define its behavior on the client side. For example, whether overlays will be created synchronously. However, certain options affect how the manager interacts with the server. These options are covered in detail below.


You can use the paddingTemplate option to set a template for the callback function that the server will wrap the response in. Using templates allows the manager to specify the appropriate callback function for each request.

The manager passes the server the name of the callback function in the 'callback' parameter.

If the name of the callback function is not set when creating the manager, the manager will automatically generate new names for these functions each time before sending a request.

'{data URL}?callback=id_1234567'.


The splitRequests option allows you to set the mode in which the manager will load data from the server. The same as LoadingObjectManager, RemoteObjectManager supports two data loading modes:

  • Data is loaded for the entire viewport simultaneously (splitRequests = false).
  • Data is loaded for the viewport by tile (splitRequests = true).

By default, splitRequests = false, meaning the manager requests data for the entire map viewport at once.

The choice of data loading mode depends on how interaction between the frontend and backend is organized. For more information about these modes, see the section Developing the backend (since RemoteObjectManager and LoadingObjectManager work in the same way, the description of modes is only given in the section for LoadingObjectManager).

Object clustering

RemoteObjectManager does not clusterize objects on the client side, but it can display results of server clusterization of data. In contrast to LoadingObjectManager, it does not support the clusterize option. In order to place cluster objects on the map, the server must return a JSON description to the manager that contains information about both placemarks and clusters. For more information about the data format, see the section Developing the backend.

Cluster objects are placed in the objectManager.ClusterCollection collection. The link to this collection is in remoteObjectManager.clusters.

Setting object options

The manager implements hierarchical inheritance for options. This means that object options are inherited from their parent collections. To set options for all manager objects, you only need to set the appropriate option for the entire collection of objects.

// Setting icon style for separate placemarks.
loadingObjectManager.objects.setObjectOptions('preset', 'islands#greenDotIcon');

// Icon style for clusters.
loadingObjectManager.clusters.options.setClusterOptions('preset', 'islands#greenClusterIcons');

The setObjectOptions and setClusterOptions methods allow setting object options “on the fly”. This means that when setting object options, the object's overlay is reconstructed, meaning the changes are immediately reflected on the map.

Object options can also be set using the set() method:

objectManager.objects.getById(1).set('preset', 'islands#greenDotIcon');

When setting options this way, their overlays will not be reconstructed. So in order for changes to be reflected on the map, you must use the set() method before the manager is added to the map.

Manager objects can be given the same options as geo objects that are instances of Placemark. The list of cluster options is given in the description of the ClusterPlacemark class.


Placemarks and clusters are represented as overlay.Placemark objects, which implement the IOverlay interface.

By default, the visual representation of manager objects is created asynchronously on request. You can use the syncOverlayInit option to set the manager to create object overlays in synchronous mode.

Links to overlays for placemarks and clusters are in objectManager.objects.overlays and objectManager.clusters.overlays, respectively.

Processing events on objects

Events on the manager's objects are propagated to the parent collections. This means that if events on the manager's placemarks or clusters must be tracked, an event handler should be assigned for the remoteObjectManager.objects and remoteObjectManager.clusters collections, respectively. The unique ID of the object where the event occurred is passed in the objectID attribute of the event.

// When pointing the mouse at placemarks, their icons turn yellow
// When the pointer moves away, the icon color turns blue.
function onObjectEvent (e) {
  var obj = e.get('target');
  if ( == 'islands#redDotIcon') {
    // The setObjectOptions method allows setting options for an object "on the fly".
    objectManager.objects.setObjectOptions(objectId, {
      preset: 'islands#yellowIcon'
  } else {
    objectManager.objects.setObjectOptions(objectId, {
      preset: 'islands#blueIcon'

// Assigning the event handler for the manager's collection of objects.['click'], onObjectEvent);

Assigning the event handler for a collection of clusters:

// When pointing the mouse at placemarks, their icons turn yellow.
// When the pointer moves away, the icon color turns blue.
function onClusterEvent (e) {
  var objectId = e.get('objectId');
  if (e.get('type') == 'mouseenter') {
    //  The setObjectOptions method allows setting options for an object "on the fly".
    remoteObjectManager.objects.setObjectOptions(objectId, {
      preset: 'islands#yellowIcon'
  } else {
    remoteObjectManager.objects.setObjectOptions(objectId, {
      preset: 'islands#blueIcon'

// Assigning the event handler for the manager's collection of cluster objects.['mouseenter', 'mouseleave'], onClusterEvent);

Sometimes events need to be tracked on a particular object of the manager. In this case, the event handler should be assigned for this object's overlay.

// When pointing the mouse at clusters, their icons turn yellow.
// When the pointer moves away, the icon color turns blue.
function onClusterEvent (e) {'');

var overlay = remoteObjectManager.objects.overlays.getById(100);'click', onOverlayEvent);