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

# Balloon

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

A balloon is a popup window that can display any HTML content. There is usually just one balloon instance on the map and it is managed via special managers (for example, [maps](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/map.Balloon.md), [geo objects](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/geoObject.Balloon.md), [hotspot layers](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/hotspot.layer.Balloon.md) and so on). Don't create them yourself, unless truly necessary.

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

## Constructor {#constructor-summary}

```javascript
Balloon(map[, options])
```

**Parameters:**

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

Reference to a map object. ||
|| [`options`](#param-options) | — | Type: Object

Options. ||
|| [`options.autoPan`](#param-options.autoPan) | true | Type: Boolean

To move the map to show the opened balloon. ||
|| [`options.autoPanCheckZoomRange`](#param-options.autoPanCheckZoomRange) | false | Type: Boolean

Enables autoscaling when it is impossible to display the map after dragging on the same scale. ||
|| [`options.autoPanDuration`](#param-options.autoPanDuration) | 500 | Type: Number

The duration of the movement to the point of the balloon (in milliseconds). ||
|| [`options.autoPanMargin`](#param-options.autoPanMargin) | 34 | Type: Number\|Number[]

Offset or offsets from the edges of the visible map area when executing autoPan. The value can be set as a single number (equal margins on all sides), as two numbers (for vertical and horizontal margins), or as four numbers (in the order of upper, right, lower, and left margins). Keep in mind that this value will be added to the value calculated in the margins manager [map.margin.Manager](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/map.margin.Manager.md). ||
|| [`options.autoPanUseMapMargin`](#param-options.autoPanUseMapMargin) | 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 executing autoPan. ||
|| [`options.closeButton`](#param-options.closeButton) | true | Type: Boolean

Flag for the Close button. ||
|| [`options.closeTimeout`](#param-options.closeTimeout) | 700 | Type: Number

Delay before closing (in ms). ||
|| [`options.contentLayout`](#param-options.contentLayout) | — | Type: Function\|String

Layout for balloon content. (Type: constructor for an object with the [ILayout](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayout.md) interface or the layout key). ||
|| [`options.interactivityModel`](#param-options.interactivityModel) | — | Type: String

Key for the interactivity model. Available keys and their values are listed in the description of [interactivityModel.storage](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/interactivityModel.storage.md). ||
|| [`options.layout`](#param-options.layout) | islands#balloon | Type: Function\|String

External layout for the balloon. (Type: constructor for an object with the [ILayout](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayout.md) interface or the layout key). ||
|| [`options.maxHeight`](#param-options.maxHeight) | — | Type: Number

Maximum height, in pixels. ||
|| [`options.maxWidth`](#param-options.maxWidth) | — | Type: Number

Maximum width, in pixels. ||
|| [`options.minHeight`](#param-options.minHeight) | — | Type: Number

Minimum height, in pixels. ||
|| [`options.minWidth`](#param-options.minWidth) | — | Type: Number

Minimum width, in pixels. ||
|| [`options.offset`](#param-options.offset) | — | Type: Number[]

Additional position offset relative to the anchor point. ||
|| [`options.openTimeout`](#param-options.openTimeout) | 150 | Type: Number

Delay before opening (in ms). ||
|| [`options.pane`](#param-options.pane) | 'balloon' | Type: String

Key of the pane that the balloon overlay is placed in. ||
|| [`options.panelContentLayout`](#param-options.panelContentLayout) | null | Type: Function\|String

The layout of the balloon contents in the panel mode. If this option is omitted, the value of the contentLayout option is used. (Type: constructor for an object with the [ILayout](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayout.md) interface or the layout key). ||
|| [`options.panelMaxHeightRatio`](#param-options.panelMaxHeightRatio) | — | Type: Number

The maximum height of the balloon panel. Defined as the coefficient relative to the map height: a number from 0 to 1. ||
|| [`options.panelMaxMapArea`](#param-options.panelMaxMapArea) | — | Type: Number

The maximum area of the map at which the balloon will be displayed in the panel mode. You can disable panel mode by setting the value to _0_, and vice versa, you can always show the balloon in panel mode by setting the value to _Infinity_. ||
|| [`options.shadow`](#param-options.shadow) | true | Type: Boolean

Flag for whether there is a shadow. ||
|| [`options.shadowLayout`](#param-options.shadowLayout) | — | Type: Function\|String

Layout for the shadow. (Type: constructor for an object with the [ILayout](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ILayout.md) interface or the layout key). ||
|| [`options.shadowOffset`](#param-options.shadowOffset) | — | Type: Number[]

Additional position offset of the shadow relative to the anchor point. ||
|| [`options.zIndex`](#param-options.zIndex) | — | Type: String

The z-index of the balloon. ||
|#

\* Mandatory parameter/option.

**Example:**

```javascript
// Creating an independent balloon instance and displaying it in the center of the map.
var balloon = new ymaps.Balloon(myMap);
// Here map options are set to parent options,
// where they contain default values for mandatory options.
balloon.options.setParent(myMap.options);
// Opening a balloon at the center of the map:
balloon.open(myMap.getCenter());
```

## Fields {#properties-summary}

#|
|| **Name** | **Type** | **Description** ||
|| [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). ||
|| [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** ||
|| [autopanbegin](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Balloon.md#event-autopanbegin)| Start of automatic shifting of the map center initiated by the autoPan method. Instance of the [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. ||
|| [autopanend](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Balloon.md#event-autopanend)| End of automatic shifting of the map center initiated by the autoPan method. Instance of the [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. ||
|| [beforeuserclose](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Balloon.md#event-beforeuserclose)| The event which precedes [Balloon.event:userclose](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Balloon.md#event-userclose). Allows you to cancel the user's action by calling the preventDefault method. Instance of the [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. ||
|| [close](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#event-close)| Closing the info object.

Inherited from [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#event-close). ||
|| [open](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#event-open)| Opening the info object.

Inherited from [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#event-open). ||
|| [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). ||
|| [userclose](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Balloon.md#event-userclose)| Balloon closed by the user. Instance of the [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. ||
|#

## Methods {#methods-summary}

#|
|| **Name** | **Returns** | **Description** ||
|| [autoPan](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IBalloon.md#autoPan)() | [vow.Promise](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/vow.Promise.md)
| Moves the map so that the balloon is visible.

Inherited from [IBalloon](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IBalloon.md#autoPan). ||
|| [close](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#close)(\[[force](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#close-param-force)]) | [vow.Promise](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/vow.Promise.md)
| Closes the info object.

Inherited from [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#close). ||
|| [getData](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#getData)() | | Returns info object data.

Inherited from [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#getData). ||
|| [getOverlay](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#getOverlay)() | [vow.Promise](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/vow.Promise.md)
| Returns the promise object to return the overlay.

Inherited from [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#getOverlay). ||
|| [getOverlaySync](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#getOverlaySync)() | [IOverlay](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IOverlay.md)
| Returns the overlay, if one exists.

Inherited from [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#getOverlaySync). ||
|| [getPosition](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#getPosition)() | | Returns the coordinates of the info object.

Inherited from [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#getPosition). ||
|| [isOpen](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#isOpen)() | Boolean
| Returns the info object state: open/closed.

Inherited from [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#isOpen). ||
|| [open](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#open)(\[[position](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#open-param-position)[, [data](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#open-param-data)]]) | [vow.Promise](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/vow.Promise.md)
| Opens the info object at the specified position. If the info object is already open, it moves it to the specified point. The format and content of the coordinates is determined by the [IProjection](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IProjection.md) that is in the options.

Inherited from [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#open). ||
|| [setData](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#setData)([data](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#setData-param-data)) | [vow.Promise](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/vow.Promise.md)
| Defines new data for the info object.

Inherited from [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#setData). ||
|| [setPosition](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#setPosition)([position](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IPopup.md#setPosition-param-position)) | [vow.Promise](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/vow.Promise.md)
| Specifies a new position for the info object.

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

## Events details {#event_detail}

### autopanbegin {#autopanbegin}

Start of automatic shifting of the map center initiated by the autoPan method. Instance of the [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class.

### autopanend {#autopanend}

End of automatic shifting of the map center initiated by the autoPan method. Instance of the [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class.

### beforeuserclose {#beforeuserclose}

The event which precedes [Balloon.event:userclose](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Balloon.md#event-userclose). Allows you to cancel the user's action by calling the preventDefault method. Instance of the [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class.

### userclose {#userclose}

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

[*star]: Mandatory parameter/option.