Documentation
Reference
2.1.50 (current version)
collection
interactivityModel
Interfaces

Balloon

Extends IBalloon, Popup.

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 (formaps, geo objects, hotspot layers and so on). Don't create them yourself, unless truly necessary.

Constructor | Fields | Events | Methods

Constructor

Balloon(map[, options])

Parameters:

ParameterDefault valueDescription
map *
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Map

Reference to a map object.

options

Type: Object

Options.

options.autoPan true

Type: Boolean

To move the map to show the opened balloon.

options.autoPanCheckZoomRange false

Type: Boolean

Enables autoscaling when it is impossible to display the map after dragging on the same scale.

options.autoPanDuration 500

Type: Number

The duration of the movement to the point of the balloon (in milliseconds).

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.

options.autoPanUseMapMargin true

Type: Boolean

Whether to account for map margins map.margin.Manager when executing autoPan.

options.closeButton true

Type: Boolean

Flag for the Close button.

options.contentLayout

Type: Function|String

Layout for balloon content. (Type: constructor for an object with the ILayout interface or the layout key).

options.layout islands#balloon

Type: Function|String

External layout for the balloon. (Type: constructor for an object with the ILayout interface or the layout key).

options.maxHeight

Type: Number

Maximum height, in pixels.

options.maxWidth

Type: Number

Maximum width, in pixels.

options.minHeight

Type: Number

Minimum height, in pixels.

options.minWidth

Type: Number

Minimum width, in pixels.

options.offset

Type: Number[]

Additional position offset relative to the anchor point.

options.pane 'balloon'

Type: String

Key of the pane that the balloon overlay is placed in.

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 interface or the layout key).

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

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 true

Type: Boolean

Flag for whether there is a shadow.

options.shadowLayout

Type: Function|String

Layout for the shadow. (Type: constructor for an object with the ILayout interface or the layout key).

options.shadowOffset

Type: Number[]

Additional position offset of the shadow relative to the anchor point.

* Mandatory parameter/option.

Example:

// 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

NameTypeDescription
beforeuserclose

The event which precedes Balloon.userclose. Allows you to cancel the user's action by calling the preventDefault method. Instance of the Event class.

eventsIEventManager

Event manager.

Inherited from IEventEmitter.

optionsIOptionManager

Options manager.

Inherited from ICustomizable.

Events

NameDescription
autopanbegin

Start of automatic shifting of the map center initiated by the autoPan method. Instance of the Event class.

autopanend

End of automatic shifting of the map center initiated by the autoPan method. Instance of the Event class.

close

Closing the info object.

Inherited from IPopup.

open

Opening the info object.

Inherited from IPopup.

optionschange

Change to the object options.

Inherited from ICustomizable.

userclose

Balloon closed by the user. Instance of the Event class.

Methods

NameReturnsDescription
autoPan()

vow.Promise

Moves the map so that the balloon is visible.

Inherited from IBalloon.

close([force])

vow.Promise

Closes the info object.

Inherited from IPopup.

getData()

Returns info object data.

Inherited from IPopup.

getOverlay()

vow.Promise

Returns the promise object to return the overlay.

Inherited from IPopup.

getOverlaySync()

IOverlay

Returns the overlay, if one exists.

Inherited from IPopup.

getPosition()

Returns the coordinates of the info object.

Inherited from IPopup.

isOpen()

Boolean

Returns the info object state: open/closed.

Inherited from IPopup.

open([position[, data]])

vow.Promise

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 that is in the options.

Inherited from IPopup.

setData(data)

vow.Promise

Defines new data for the info object.

Inherited from IPopup.

setPosition(position)

vow.Promise

Specifies a new position for the info object.

Inherited from IPopup.

Fields details

beforeuserclose

beforeuserclose

The event which precedes Balloon.userclose. Allows you to cancel the user's action by calling the preventDefault method. Instance of the Event class.

Events details

autopanbegin

Start of automatic shifting of the map center initiated by the autoPan method. Instance of the Event class.

autopanend

End of automatic shifting of the map center initiated by the autoPan method. Instance of the Event class.

userclose

Balloon closed by the user. Instance of the Event class.