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

# objectManager.ClusterCollection

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

Collection of clusters generated by [ObjectManager](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ObjectManager.md). Clusters are added to and deleted from the collection automatically, and are read-only. The cluster object is a JSON structure the same as the objects in the layer. Cluster object field: 
- id - Unique cluster ID.
- geometry - Description of the cluster geometry.
- properties - Description of the cluster data. The properties.geoObjects field stores an array 	of objects that are included in the cluster.
- options - Cluster options. Optional field.

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

## Constructor {#constructor-summary}

```javascript
objectManager.ClusterCollection()
```

## Fields {#properties-summary}

#|
|| **Name** | **Type** | **Description** ||
|| [balloon](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#balloon) | [objectManager.Balloon](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.Balloon.md) | Cluster balloon in the manager. ||
|| [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). ||
|| [hint](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#hint) | [objectManager.Hint](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.Hint.md) | Object hint in the [ObjectManager](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ObjectManager.md). Names of fields available via [Event.get](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md#get): 
- objectId - ID of the object where the hint was shown. ||
|| [options](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#options) | [option.Manager](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/option.Manager.md) | Options manager. Names of fields that are available via the option.Manager#get method: 
- hasBalloon - Indicates whether the collection 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.
- hasHint - Indicates whether the collection 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.
- hideIconOnBalloonOpen - Hide the icon when opening the balloon. Default value: true.
- openBalloonOnClick - Option that allows you to forbid opening the balloon when clicking on a cluster. By default, opening the balloon is allowed.
- openHintOnHover - Option that allows you to forbid displaying the popup hint when the cluster is pointed at. By default, showing hints is allowed. ||
|| [overlays](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#overlays) | [objectManager.OverlayCollection](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.OverlayCollection.md) | Collection of cluster overlays. All events, with the exception of "add" and "remove" events, propagate from the collection of overlays to the collection of clusters. ||
|| [state](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#state) | [data.Manager](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/data.Manager.md) | State of the collection of clusters. Defined by the following fields: 
- activeObject - JSON description of the object selected in the cluster balloon. ||
|#

## Events {#events-summary}

#|
|| **Name** | **Description** ||
|| [add](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#event-add) | Adds a cluster to the collection. Instance of the [Event](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. Names of fields that are available via the [Event.get](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md#get) method: 
- objectId - ID of the added object.
- child - The added object. ||
|| [clusteroptionschange](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#event-clusteroptionschange) | Modification of cluster options via the [objectManager.ClusterCollection.setClusterOptions](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#setClusterOptions) method. Instance of the [Event](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. Names of fields that are available via the [Event.get](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md#get) method: 
- objectId - ID of the cluster that had options modified. ||
|| [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). ||
|| [remove](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#event-remove) | Deletes a cluster from the collection. Instance of the [Event](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. Names of fields that are available via the [Event.get](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md#get) method: 
- objectId - ID of the deleted object.
- child - The deleted object. ||
|#

## Methods {#methods-summary}

#|
|| **Name** | **Returns** | **Description** ||
|| [each](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#each)([callback](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#each-param-callback), [context](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#each-param-context)) | | ||
|| [getAll](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#getAll)() | Object[] | Returns array of objects contained in the collection. ||
|| [getById](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#getById)([id](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#getById-param-id)) | Object\|null | Returns cluster object with the specified ID, or null if this cluster does not exist. ||
|| [getIterator](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#getIterator)() | [IIterator](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IIterator.md) | Returns iterator for the collection. ||
|| [getLength](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#getLength)() | Number | Returns the number of objects in the collection. ||
|| [getObjectManager](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#getObjectManager)() | [ObjectManager](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ObjectManager.md) | Returns the parent layer of objects in the collection. ||
|| [setClusterOptions](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#setClusterOptions)([objectId](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#setClusterOptions-param-objectId), [options](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#setClusterOptions-param-options)) | [objectManager.ObjectCollection](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ObjectCollection.md) | Returns self-reference. ||
|#

## Fields details {#field_detail}

### balloon {#balloon}

```javascript
{objectManager.Balloon} balloon
```

Cluster balloon in the manager.

### hint {#hint}

```javascript
{objectManager.Hint} hint
```

Object hint in the [ObjectManager](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ObjectManager.md). Names of fields available via [Event.get](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md#get): 
- objectId - ID of the object where the hint was shown.

### options {#options}

```javascript
{option.Manager} options
```

Options manager. Names of fields that are available via the option.Manager#get method: 
- hasBalloon - Indicates whether the collection 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.
- hasHint - Indicates whether the collection 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.
- hideIconOnBalloonOpen - Hide the icon when opening the balloon. Default value: true.
- openBalloonOnClick - Option that allows you to forbid opening the balloon when clicking on a cluster. By default, opening the balloon is allowed.
- openHintOnHover - Option that allows you to forbid displaying the popup hint when the cluster is pointed at. By default, showing hints is allowed.

**Example:**

```javascript
objectManager.objects.options.set({
    preset: 'islands#greenDotIcon',
    hintContentLayout: ymaps.templateLayoutFactory.createClass('{{propeties.name}}')
});
```

### overlays {#overlays}

```javascript
{objectManager.OverlayCollection} overlays
```

Collection of cluster overlays. All events, with the exception of "add" and "remove" events, propagate from the collection of overlays to the collection of clusters.

**Example:**

```javascript
// Changing the color of the cluster icon when moused over.
objectManager.clusters.events.add(['mouseenter', 'mouseleave'], function (e) {
    var objectId = e.get('objectId');
    var overlay = objectManager.clusters.overlays.getById(objectId);
    if (e.get('type') == 'mouseenter') {
        setRedColor(objectId);
        overlay.events.add('mapchange', onMapChange);
    } else {
        setGreenColor(objectId);
        overlay.events.remove('mapchange', onMapChange);
    }
});

function onMapChange (e) {
    setGreenColor(objectManager.clusters.overlays.getId(e.get('target')));
}

function setGreenColor (objectId) {
    objectManager.clusters.setClusterOptions(objectId, {
        preset: 'islands#greenClusterIcons'
    });
}

function setRedColor (objectId) {
    objectManager.clusters.setClusterOptions(objectId, {
        preset: 'islands#redClusterIcons'
    });
}
```

### state {#state}

```javascript
{data.Manager} state
```

State of the collection of clusters. Defined by the following fields: 
- activeObject - JSON description of the object selected in the cluster balloon.

**Example:**

```javascript
// Opening the cluster balloon with the selected object.
var objectState = objectManager.getObjectState(myObjects[i]);
if (objectState.isClustered) {
    objectManager.clusters.state.set('activeObject', myObjects[i]);
    objectManager.clusters.balloon.open(objectState.cluster.id);
}
```

## Events details {#event_detail}

### add {#add}

Adds a cluster to the collection. Instance of the [Event](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. Names of fields that are available via the [Event.get](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md#get) method: 
- objectId - ID of the added object.
- child - The added object.

### clusteroptionschange {#clusteroptionschange}

Modification of cluster options via the [objectManager.ClusterCollection.setClusterOptions](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/objectManager.ClusterCollection.md#setClusterOptions) method. Instance of the [Event](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. Names of fields that are available via the [Event.get](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md#get) method: 
- objectId - ID of the cluster that had options modified.

### remove {#remove}

Deletes a cluster from the collection. Instance of the [Event](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. Names of fields that are available via the [Event.get](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md#get) method: 
- objectId - ID of the deleted object.
- child - The deleted object.

## Methods details {#method_detail}

### each {#each}

```javascript
{} each(callback, context)
```

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`callback`](#each-param-callback)[*](*star) | — | Type: Function

Callback function that the collection objects are passed to. ||
|| [`context`](#each-param-context)[*](*star) | — | Type: Object

Context for the callback. ||
|#

\* Mandatory parameter/option.

**Example:**

```javascript
var clusterizedObjectsCounter = 0;
objectManager.clusters.each(function (cluster) {
    clusterizedObjectsCounter += cluster.properties.geoObjects.length;
});
alert('The map shows ' + clusterizedObjectsCounter + ' clusterized objects.');
```

### getAll {#getAll}

```javascript
{Object[]} getAll()
```

**Returns** array of objects contained in the collection.

**Example:**

```javascript
var clusterArray = objectManager.clusters.getAll();
```

### getById {#getById}

```javascript
{Object|null} getById(id)
```

**Returns** cluster object with the specified ID, or null if this cluster does not exist.

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`id`](#getById-param-id)[*](*star) | — | Type: String

Cluster ID. ||
|#

\* Mandatory parameter/option.

**Example:**

```javascript
// Making the cluster color change if it has more than 20 objects.
objectManager.clusters.events.add('add', function (e) {
    var cluster = objectManager.clusters.getById(e.get('objectId'));
    var objects = cluster.properties.geoObjects;
    if (objects.length > 20) {
        objectManager.clusters.setClusterOptions(cluster.id, {
            preset: 'islands#redClusterIcons'
        });
    }
});
```

### getIterator {#getIterator}

```javascript
{IIterator} getIterator()
```

**Returns** iterator for the collection.

**Example:**

```javascript
var clusterizedObjectsCounter = 0;
var it = objectManager.clusters.getIterator();
var cluster;
while ((cluster = it.getNext()) != it.STOP_ITERATION) {
    clusterizedObjectsCounter += cluster.properties.geoObjects.length;
}
alert('The map displays ' + clusterizedObjectsCounter + ' clusterized objects.');
```

### getLength {#getLength}

```javascript
{Number} getLength()
```

**Returns** the number of objects in the collection.

**Example:**

```javascript
alert('The map displays ' + objectManager.clusters.getLength() + ' clusters.');
```

### getObjectManager {#getObjectManager}

```javascript
{ObjectManager} getObjectManager()
```

**Returns** the parent layer of objects in the collection.

### setClusterOptions  {#setClusterOptions}

```javascript
{objectManager.ObjectCollection} setClusterOptions(objectId, options)
```

**Returns** self-reference.

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`objectId`](#setClusterOptions-param-objectId)[*](*star) | — | Type: String

Cluster ID. ||
|| [`options`](#setClusterOptions-param-options)[*](*star) | — | Type: Object

Object with cluster options. ||
|#

\* Mandatory parameter/option.

**Example:**

```javascript
// Making the cluster color change if it has more than 20 objects.
objectManager.clusters.events.add('add', function (e) {
    var cluster = objectManager.clusters.getById(e.get('objectId'));
    var objects = cluster.properties.geoObjects;
    if (objects.length > 20) {
        objectManager.clusters.setClusterOptions(cluster.id, {
            preset: 'islands#redClusterIcons'
        });
    }
});
```

[*star]: Mandatory parameter/option.