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

Constructor | Fields | Events | Methods

Constructor

Balloon(map[, options])

Parameters:

Parameter

Default value

Description

map*

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.closeTimeout

700

Type: Number

Delay before closing (in ms).

options.contentLayout

Type: Function|String

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

options.interactivityModel

Type: String

Key for the interactivity model. Available keys and their values are listed in the description of interactivityModel.storage.

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.openTimeout

150

Type: Number

Delay before opening (in ms).

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.

options.zIndex

Type: String

The z-index of the balloon.

* 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

Name

Type

Description

events

IEventManager

Event manager.

Inherited from IEventEmitter.

options

IOptionManager

Options manager.

Inherited from ICustomizable.

Events

Name

Description

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.

beforeuserclose

The event which precedes Balloon.event:userclose. Allows you to cancel the user's action by calling the preventDefault 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

Name

Returns

Description

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.

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.

beforeuserclose

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

userclose

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