Documentation
Reference
2.1.50 (current version)
collection
interactivityModel
Interfaces
2.1.52 (release candidate)
collection
interactivityModel
Interfaces

Clusterer

Extends IChildOnMap, ICustomizable, IEventEmitter, IParentOnMap.

Geo object clusterer. Clusterizes objects in the visible area of the map. If the object does not fall within the visible area of the map, it will not be added to the map. Note, that the clusterer does not react to changing the coordinates of objects (either programmatically, or as the result of dragging). If you want to change the coordinates of some object in the clusterer, you should first delete the object from the clusterer and then add it back.

See ClusterPlacemark

Constructor | Fields | Events | Methods

Constructor

Clusterer([options])

Parameters:

ParameterDefault valueDescription
options

Type: Object

Options. Options for child cluster objects are set with the "cluster" prefix. See ClusterPlacemark.

options.gridSize 64

Type: Number

The size of cluster cells, in pixels. The value must be equal 2^n (an area of 256 by 256 pixels should fit an even number of cells).

options.groupByCoordinates false

Type: Boolean

Special operation mode of the clusterer allowing clusters to be formed only from geo objects with the same coordinates.

options.hasBalloon true

Type: Boolean

Flag whether the clusterer has the .balloon field. If a balloon doesn't need to be opened when clicking the cluster, we recommend setting this option to the "false" value to avoid unnecessary initializations.

options.hasHint true

Type: Boolean

Flag whether the clusterer has the .hint field. If a popup hint doesn't need to be displayed when the cluster is pointed at, we recommend setting this option to the "false" value to avoid unnecessary initializations.

options.margin 10

Type: Number[][]|Number[]

Number or array of numbers that set the offset for the cluster center relative to the clusterization cells. If a single number is set, it is applied to each side. If two numbers are set, they are the vertical and horizontal offsets, respectively. If an array of four numbers is set, they are the top, right, bottom, and left margins.

options.maxZoom Infinity

Type: Number[]

The maximum map zoom that object clusterization occurs at. Even if clusterization is disabled, only objects in the visible map area will be shown.

options.minClusterSize 2

Type: Number

Minimum number of objects to make up a cluster.

options.preset

Type: String

Key for the clusterer's preset options. A list of keys available in the package.clusters package can be found in the description of option.presetStorage.

options.showInAlphabeticalOrder false

Type: Boolean

Show placemarks in the balloon in alphabetical order when the cluster is clicked on. The cluster's geo objects are sorted by special fields in the data of these geo objects - clusterCaption (or balloonContentHeader, if the previous field is not defined). By default, geo objects are shown in the order in which they were added to the clusterer.

options.useMapMargin true

Type: Boolean

Whether to account for map margins map.margin.Manager when zooming the map in after a click on a cluster.

options.viewportMargin 128

Type: Number[][]|Number[]

The offset of the area in which you are clustering. Clustering is performed for the visible area of the map. Use this option to expand the area of clustering relative to the visible area of the map.

options.zoomMargin 0

Type: Number[][]|Number[]

Offset from the map viewport borders to observe when zooming in the map after a cluster is clicked. Recommended to set this option's value to match the size of the cluster icons and placemarks. For example, if only the bottom half of a placemark falls on the visible area of the map, a nonzero "top" offset should be set, so the placemark remains completely visible after the cluster is broken up. If a single number is set, it is applied to each side. If two numbers are set, they are the horizontal and vertical margins, respectively. If an array of four numbers is set, they are the top, right, bottom, and left margins.

Example:

// Creating a clusterer

// Creating a map that requires clusterization of geo objects
var map = new ymaps.Map('mapsID', { center: [56.034, 36.992], zoom: 8 }),
// Creating an array of geo objects
myGeoObjects = [];
myGeoObjects[0] = new ymaps.GeoObject({
    geometry: { type: "Point", coordinates: [56.034, 36.992] },
    properties: {
        clusterCaption: 'Geo object №1',
        balloonContentBody: 'Balloon content for geo object №1'
    }
});
myGeoObjects[1] = new ymaps.GeoObject({
    geometry: { type: "Point", coordinates: [56.021, 36.983] },
    properties: {
        clusterCaption: 'Geo object №2',
        balloonContentBody: 'Balloon content for geo object №2'
   }
});

// Creating a cluster and prohibiting zooming the map in when the cluster is clicked
var clusterer = new ymaps.Clusterer({ clusterDisableClickZoom: true });
clusterer.add(myGeoObjects);
map.geoObjects.add(clusterer);

Fields

NameTypeDescription
balloonclusterer.Balloon

Clusterer's balloon.

balloonclose

Closing the balloon.

  • target - Link to the clusterer balloon manager.
  • cluster - Reference to the cluster object.
Instance of the Event class.

balloonopen

Opening a balloon on a cluster. Names of fields that are available via the Event.get method:

  • target - Link to the clusterer balloon manager.
  • cluster - Reference to the cluster object.
Instance of the Event class.

eventsIEventManager

Event manager.

Inherited from IEventEmitter.

hintclusterer.hint

Clusterer's hint.

optionsIOptionManager

Options manager.

Inherited from ICustomizable.

Events

NameDescription
hintclose

Closing the hint. Instance of the Event class.

hintopen

Opening a hint on a cluster. Instance of the Event class.

mapchange

Map reference changed. Data fields:

  • oldMap - Old map.
  • newMap - New map.

Inherited from IParentOnMap.

optionschange

Change to the object options.

Inherited from ICustomizable.

parentchange

The parent object reference changed.

Data fields:

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

Inherited from IChild.

Methods

NameReturnsDescription
add(objects)

Clusterer

Adds a geo object or array of geo objects to the clusterer.

createCluster(center, geoObjects)

IGeoObject

Function for creating a cluster using the clusterer. Called directly by the clusterer during the clusterization process. Accepts as input the cluster center and an array of geo objects that go in this cluster. Returns the cluster, which will later be added to the map. If you need the clusterer to create user cluster objects, you should redefine this method for the clusterer.

getBounds()

Number[][]|null

Returns the geographical coordinates of the rectangular area that includes all the clusterer elements.

getClusters()

IGeoObject[]

Method for getting the current array of cluster objects. Note that the cluster objects change when you change the map zoom or shift its center. If you want to perform operations on all clusters, it is better to redefine the createCluster method and add the required operations to its call.

getGeoObjects()

IGeoObject[]

Returns an array of geo objects added to the clusterer.

getMap()

Map

Returns reference to the map.

Inherited from IParentOnMap.

getObjectState(geoObject)

Object

Function for getting information about the current state of an object that was added to the clusterer.

getParent()

IControlParent|null

Returns link to the parent object, or null if the parent element was not set.

Inherited from IChildOnMap.

remove(objects)

Clusterer

Removes geo objects from the clusterer.

removeAll()

Clusterer

Removes all geo objects from the clusterer.

setParent(parent)

IChildOnMap

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.

Fields details

balloon

Clusterer's balloon.

balloonclose

balloonclose

Closing the balloon.

  • target - Link to the clusterer balloon manager.
  • cluster - Reference to the cluster object.
Instance of the Event class.

balloonopen

balloonopen

Opening a balloon on a cluster. Names of fields that are available via the Event.get method:

  • target - Link to the clusterer balloon manager.
  • cluster - Reference to the cluster object.
Instance of the Event class.

Example:

clusterer.events.add('balloonopen', function (e) {
    var clusterPlacemark = e.get('cluster');
});

hint

{clusterer.hint} hint

Clusterer's hint.

Events details

hintclose

Closing the hint. Instance of the Event class.

hintopen

Opening a hint on a cluster. Instance of the Event class.

Methods details

add

Adds a geo object or array of geo objects to the clusterer.

Returns self-reference.

Parameters:

ParameterDefault valueDescription
objects*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: IGeoObject[][]|IGeoObject[]

Array of geo objects, or a single geo object.

* Mandatory parameter/option.

Example:

var myPlacemark = new ymaps.Placemark([35, 21]);
clusterer.add(myPlacemark);
var placemarks = [
    new ymaps.Placemark([44, 55]),
    new ymaps.Placemark([34, 45])
];
clusterer.add(placemarks);

createCluster

{IGeoObject} createCluster(center, geoObjects)

Function for creating a cluster using the clusterer. Called directly by the clusterer during the clusterization process. Accepts as input the cluster center and an array of geo objects that go in this cluster. Returns the cluster, which will later be added to the map. If you need the clusterer to create user cluster objects, you should redefine this method for the clusterer.

Returns the cluster object. By default, creates instances of the ClusterPlacemark.

Parameters:

ParameterDefault valueDescription
center*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number[]

The cluster center in geocoordinates.

geoObjects*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: IGeoObject[]

Array of placemarks in the cluster.

* Mandatory parameter/option.

Example:

// Setting a hint for clusters depending on their contents.
var clusterer = new ymaps.Clusterer();
clusterer.createCluster = function (center, geoObjects) {
    // Creating a cluster placemark using a standard implementation of the method.
    var clusterPlacemark = ymaps.Clusterer.prototype.createCluster.call(this, center, geoObjects),
        geoObjectsLength = clusterPlacemark.getGeoObjects().length,
        hintContent;
    if (geoObjectsLength < 10) {
        hintContent = 'Very few placemarks';
    } else if (geoObjectsLength < 100) {
        hintContent = 'That's OK with placemarks';
    } else {
        hintContent = 'A lot of placemarks';
    }
    clusterPlacemark.properties.set('hintContent', hintContent);
    return clusterPlacemark;
};

getBounds

{Number[][]|null} getBounds()

Returns the geographical coordinates of the rectangular area that includes all the clusterer elements.

Example:

var clusterer = new ymaps.Clusterer();
clusterer.add(myPlacemarks);
map.setBounds(clusterer.getBounds());
map.geoObjects.add(clusterer);

getClusters

{IGeoObject[]} getClusters()

Method for getting the current array of cluster objects. Note that the cluster objects change when you change the map zoom or shift its center. If you want to perform operations on all clusters, it is better to redefine the createCluster method and add the required operations to its call.

Returns an array of clusters added to the map at this moment.

Example:

map.events.add('boundschange', function () {
    var clusters = clusterer.getClusters();
    alert('The map has moved and ' + clusters.length + ' clusters are displayed now.');
});

getGeoObjects

{IGeoObject[]} getGeoObjects()

Returns an array of geo objects added to the clusterer.

Example:

// Counting objects in the visible area of the map.
var geoObjects = clusterer.getGeoObjects(),
    shownObjectsCounter = 0;
for (var i = 0, l = geoObjects.length; i < l; i++) {
    if (clusterer.getObjectState(geoObjects[i]).isShown) {
        shownObjectsCounter++;
    }
}
alert('shownObjectsCounter + ' out of ' + geoObjects.length + ' placemarks are displayed on the map.');

getObjectState

{Object} getObjectState(geoObject)

Function for getting information about the current state of an object that was added to the clusterer.

Returns object with following fields:

  • isShown - Indicates whether an object is in the visible area of the map.
  • cluster - A reference to the cluster the object was added to.
  • isClustered - Indicates whether the object was put in the cluster.
.

Parameters:

ParameterDefault valueDescription
geoObject*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: IGeoObject

The geo object to get the state for.

* Mandatory parameter/option.

Example:

// Opening the cluster balloon with the selected object.
// Getting the info about the object's state within the cluster.
var geoObjectState = clusterer.getObjectState(myGeoObjects[1]);
// Checking if the object is located inside the visible area of the map.
if (geoObjectState.isShown) {

    // If the object is put in the cluster, the cluster balloon with the appropriate object is opened.
    if (geoObjectState.isClustered) {
        geoObjectState.cluster.state.set('activeObject', myGeoObjects[1]);
        clusterer.balloon.open(geoObjectState.cluster);

    } else {
        // If the object was not in the cluster, its own balloon is  opened.
        myGeoObjects[1].balloon.open();
    }
}

remove

{Clusterer} remove(objects)

Removes geo objects from the clusterer.

Returns self-reference.

Parameters:

ParameterDefault valueDescription
objects*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: IGeoObject[][]|IGeoObject[]

Array of geo objects.

* Mandatory parameter/option.

Example:

var myPlacemark = new ymaps.Placemark([35, 21]),
    placemarks = [
        new ymaps.Placemark([44, 55]),
        new ymaps.Placemark([34, 45]),
        ...
    ];
clusterer.add(myPlacemark).add(placemarks);
...
// Deleting the first 10 objects of the array from the clusterer.
clusterer.remove(placemarks.slice(0, 10));

removeAll

{Clusterer} removeAll()

Removes all geo objects from the clusterer.

Returns self-reference.

Example:

clusterer.add(placemark1);
clusterer.add(placemark2);
clusterer.removeAll();