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

# Clusterer

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

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](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ClusterPlacemark.md)

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

## Constructor {#constructor-summary}

```javascript
Clusterer([options])
```

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`options`](#param-options) | — | Type: Object

Options. Options for child cluster objects are set with the "cluster" prefix. See [ClusterPlacemark](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ClusterPlacemark.md). ||
|| [`options.gridSize`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-options.minClusterSize) | 2 | Type: Number

Minimum number of objects to make up a cluster. ||
|| [`options.preset`](#param-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](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/option.presetStorage.md). ||
|| [`options.showInAlphabeticalOrder`](#param-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`](#param-options.useMapMargin) | true | Type: Boolean

Whether to account for map margins [map.margin.Manager](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/map.margin.Manager.md) when zooming the map in after a click on a cluster. ||
|| [`options.viewportMargin`](#param-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`](#param-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:**

```javascript
// 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 {#properties-summary}

#|
|| **Name** | **Type** | **Description** ||
|| [balloon](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#balloon) | [clusterer.Balloon](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/clusterer.Balloon.md)| Clusterer's balloon. ||
|| [balloonclose](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#balloonclose) | | Closing the balloon. 
- target - Link to the clusterer balloon manager.
- cluster - Reference to the cluster object.
Instance of the Event class. ||
|| [balloonopen](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#balloonopen) | | Opening a balloon on a cluster. Names of fields that are available via the [Event.get](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md#get) method: 
- target - Link to the clusterer balloon manager.
- cluster - Reference to the cluster object.
Instance of the Event class. ||
|| [events](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IEventEmitter.md#events) | [IEventManager](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IEventManager.md)| Event manager.

Inherited from [IEventEmitter](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IEventEmitter.md#events). ||
|| [hint](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#hint) | clusterer.hint| Clusterer's hint. ||
|| [options](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICustomizable.md#options) | [IOptionManager](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IOptionManager.md)| Options manager.

Inherited from [ICustomizable](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICustomizable.md#options). ||
|#

## Events {#events-summary}

#|
|| **Name** | **Description** ||
|| [hintclose](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#event-hintclose)| Closing the hint. Instance of the [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. ||
|| [hintopen](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#event-hintopen)| Opening a hint on a cluster. Instance of the [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. ||
|| [mapchange](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IParentOnMap.md#event-mapchange)| Map reference changed. Data fields: 
- oldMap - Old map.
- newMap - New map.

Inherited from [IParentOnMap](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IParentOnMap.md#event-mapchange). ||
|| [optionschange](https://yandex.com.tr/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.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICustomizable.md#event-optionschange). ||
|| [parentchange](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChild.md#event-parentchange)| The parent object reference changed.

Data fields:

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

Inherited from [IChild](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChild.md#event-parentchange). ||
|#

## Methods {#methods-summary}

#|
|| **Name** | **Returns** | **Description** ||
|| [add](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#add)([objects](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#add-param-objects)) | [Clusterer](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md)
| Adds a geo object or array of geo objects to the clusterer. ||
|| [createCluster](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#createCluster)([center](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#createCluster-param-center), [geoObjects](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#createCluster-param-geoObjects)) | [IGeoObject](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IGeoObject.md)
| 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](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#getBounds)() | Number[][]\|null
| Returns the geographical coordinates of the rectangular area that includes all the clusterer elements. ||
|| [getClusters](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#getClusters)() | [IGeoObject](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IGeoObject.md)[]
| 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](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#getGeoObjects)() | [IGeoObject](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IGeoObject.md)[]
| Returns an array of geo objects added to the clusterer. ||
|| [getMap](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IParentOnMap.md#getMap)() | [Map](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Map.md)
| Returns reference to the map.

Inherited from [IParentOnMap](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IParentOnMap.md#getMap). ||
|| [getObjectState](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#getObjectState)([geoObject](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#getObjectState-param-geoObject)) | Object
| Function for getting information about the current state of an object that was added to the clusterer. ||
|| [getParent](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md#getParent)() | [IParentOnMap](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IParentOnMap.md)\|null
| Returns link to the parent object, or null if the parent element was not set.

Inherited from [IChildOnMap](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md#getParent). ||
|| [remove](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#remove)([objects](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#remove-param-objects)) | [Clusterer](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md)
| Removes geo objects from the clusterer. ||
|| [removeAll](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md#removeAll)() | [Clusterer](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Clusterer.md)
| Removes all geo objects from the clusterer. ||
|| [setParent](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md#setParent)([parent](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md#setParent-param-parent)) | [IChildOnMap](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md)
| 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](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md#setParent). ||
|#

## Fields details {#field_detail}

### balloon {#balloon}

```javascript
{clusterer.Balloon} balloon
```

Clusterer's balloon.

### balloonclose {#balloonclose}

```javascript
balloonclose
```

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

### balloonopen {#balloonopen}

```javascript
balloonopen
```

Opening a balloon on a cluster. Names of fields that are available via the [Event.get](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md#get) method: 
- target - Link to the clusterer balloon manager.
- cluster - Reference to the cluster object.
Instance of the Event class.

**Example:**

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

### hint {#hint}

```javascript
{clusterer.hint} hint
```

Clusterer's hint.

## Events details {#event_detail}


### hintclose {#hintclose}

Closing the hint. Instance of the [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class.

### hintopen {#hintopen}

Opening a hint on a cluster. Instance of the [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class.

## Methods details {#method_detail}

### add {#add}

```javascript
{Clusterer} add(objects)
```

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

**Returns** self-reference.

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`objects`](#add-param-objects)[*](*star) | — | Type: [IGeoObject](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IGeoObject.md)\|[IGeoObject](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IGeoObject.md)[]

Array of geo objects, or a single geo object. ||
|#

\* Mandatory parameter/option.

**Example:**

```javascript
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 {#createCluster}

```javascript
{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](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ClusterPlacemark.md).

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`center`](#createCluster-param-center)[*](*star) | — | Type: Number[]

The cluster center in geocoordinates. ||
|| [`geoObjects`](#createCluster-param-geoObjects)[*](*star) | — | Type: [IGeoObject](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IGeoObject.md)[]

Array of placemarks in the cluster. ||
|#

\* Mandatory parameter/option.

**Example:**

```javascript
// 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 {#getBounds}

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

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

**Example:**

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

### getClusters {#getClusters}

```javascript
{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:**

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

### getGeoObjects {#getGeoObjects}

```javascript
{IGeoObject[]} getGeoObjects()
```

**Returns** an array of geo objects added to the clusterer.

**Example:**

```javascript
// 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  {#getObjectState}

```javascript
{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:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`geoObject`](#getObjectState-param-geoObject)[*](*star) | — | Type: [IGeoObject](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IGeoObject.md)

The geo object to get the state for. ||
|#

\* Mandatory parameter/option.

**Example:**

```javascript
// 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 {#remove}

```javascript
{Clusterer} remove(objects)
```

Removes geo objects from the clusterer.

**Returns** self-reference.

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`objects`](#remove-param-objects)[*](*star) | — | Type: [IGeoObject](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IGeoObject.md)\|[IGeoObject](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IGeoObject.md)[]

Array of geo objects. ||
|#

\* Mandatory parameter/option.

**Example:**

```javascript
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 {#removeAll}

```javascript
{Clusterer} removeAll()
```

Removes all geo objects from the clusterer.

**Returns** self-reference.

**Example:**

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

[*star]: Mandatory parameter/option.