Documentation
Reference
2.1.50 (current version)
collection
interactivityModel
Interfaces

Map

Creating and deleting maps

Use the Map class to create a map. In the class constructor, you must specify the map center and zoom level, as well as the HTML element that it will be placed in.

To define the HTML element, you can use a reference to the element, or its identifier (the value of the "id" attribute).

<head>
<script type="text/javascript">
    var moscow_map,
        piter_map;
        
    ymaps.ready(function(){
        moscow_map = new ymaps.Map("first_map", {
            center: [55.76, 37.64],
            zoom: 10
        });
        piter_map = new ymaps.Map(document.getElementsByTagName('p')[2], {
            center: [59.94, 30.32],
            zoom: 9
        });
    });
</script>
</head>
<body>
    <p>Map of Moscow</p>
    <div id="first_map" style="width:400px; height:300px"></div>
    <p>Map of Saint Petersburg</p>
    <p style="width:400px; height:200px"></p>
</body>

The map can be placed in any HTML block element and completely fills the rectangular area it occupies.

The dimensions of the area are calculated during initialization. During the constructor call, if the map container is not formed in the DOM tree or its dimensions have not been defined, a zero-size map will be created (meaning the map will not really be displayed). This situation frequently occurs when placing the map in a hidden container.

The map parameters that are set during initialization can be changed.

Use the destroy method to delete a map.

See the Example.

Map parameters

The main map parameters are the DOM element that the map is placed in (the viewport), the area to display (the mapping region), and the way of displaying it (the map type).

When creating a map, you must set the mapping region by specifying the map center and zoom level. After this, the mapping region can be changed using the methods setCenter, panTo, setGlobalPixelCenter, setZoom, or setBounds.

myMap.setCenter([55.7, 37.6], 6);
myMap.panTo([50.451, 30.522], {duration: 2000});
myMap.setBounds([[50.1, 30.2],[60.3, 20.4]]);

The map type can be specified in the constructor, or using the setType method. You can use the built-in map types, or custom ones. The built-in map types include (corresponding keys for these types are shown in parentheses):

  • Roadmap ('yandex#map')
  • Satellite ('yandex#satellite')
  • Hybrid ('yandex#hybrid')

A list of cities that have detailed maps available (down to the building level) for the built-in map types can be found on the page http://maps.yandex.ru?index.

myMap.setType('yandex#satellite');

See the Example.

Behaviors

The map has a set of behaviors that define the map's response to user actions. For example, when moving the mouse cursor across the viewport with the left mouse button held down, the map moves with the cursor.

When the map is initialized, it is assigned a set of behaviors that can be changed later. Map behaviors can be accessed via the behaviors field.

myMap.behaviors
    // Disabling certain behaviors that are enabled by default:
    //  - drag - dragging the map with the left mouse button held down.
    //  - rightMouseButtonMagnifier - zooming in on the area selected with the right mouse button.
    .disable(['drag', 'rightMouseButtonMagnifier'])
    // Enabling the distance ruler that is activated by
    // left-click.
    .enable('ruler');

Custom behaviors are defined by implementing the IBehavior interface. To create a custom behavior, it is sufficient to create a class and define its properties: the behavior options manager and the event manager. The class methods must also be defined: enable, disable, setParent and getParent. Next, the class is added to the map behavior storage ymaps.behavior.storage, then the map.behaviors behavior manager creates an instance of this class - the new behavior.

// Creating and adding a map behavior for 
// centering the map at the point where it is clicked.
// To do this, we create the MyBehavior class and define its properties and methods
function MyBehavior() {
    // Defining class properties
    this.options = new ymaps.option.Manager(); // Options manager
    this.events = new ymaps.event.Manager(); // Event manager
}

// Defining methods
MyBehavior.prototype = {
    constructor: MyBehavior,
    // When the behavior is enabled, the click event is added to the map
    enable: function () {
        /* this._parent - the behavior manager is the parent to the behavior.
           this._parent.getMap() - getting a reference to the map.
           this._parent.getMap().events.add - adding a listener for map events. */
        this._parent.getMap().events.add('click', this._onClick, this);
    },
    disable: function () {
        this._parent.getMap().events.remove('click', this._onClick, this);
    },
    // Sets the parent for the source behavior
    setParent: function (parent) { this._parent = parent; },
    // Gets the parent
    getParent: function () { return this._parent; },
    // When the map is clicked, it is centered on the clicked point
    _onClick: function (e) {
        var coords = e.get('coords');
        this._parent.getMap().setCenter(coords);
    }
};

// Adding the created class to the behavior storage. Now this behavior will be available using the 'mybehavior' key.
ymaps.behavior.storage.add('mybehavior', MyBehavior);
// Enabling the behavior
myMap.behaviors.enable('mybehavior');

Balloon and hint

The map can display one balloon (popup window) and one hint.

The balloon and hint are displayed at a point with set coordinates, and their content may contain HTML markup. References to instances of the map balloon and hint classes are contained in the balloon and hint fields of a map object.

myMap.balloon.open(myMap.getCenter(),
    {
        contentHeader: 'A long time ago',
        contentBody: 'In a galaxy' +
        ' <span style="color:red; font-weight:bold">far</span>' +
        ' far <b>away</b>',
    }
);
myMap.hint.open([55.76, 37.38],
    'May the <em>Force</em> be with you!'
);

Geo objects and hotspots have access to the map balloon and hint. This means the balloon or hint can be opened over a geo object or hotspot without explicitly setting the balloon/hint coordinates.

var myPlacemark = new ymaps.Placemark([55.7, 37.6], {
    balloonContentHeader: 'A long time ago',
    balloonContentBody: 'In a galaxy',
    balloonContentFooter: 'Far, Far Away...',
    hintContent: 'May the Force be with you!'
});
// The balloon opens at the balloon anchor point, i.e. over the placemark.
myPlacemark.balloon.open();

If there is already a balloon open on the map when the balloon is opening, the old balloon is closed and the new one is opened. The same applies to the hint.

To customize the appearance of the balloon and hint, use the options or templates.

Note. Note that opening a balloon or hint is an asynchronous operation, and open methods return Promise objects.

Sometimes there may be a situation when the balloon goes outside of the map boundaries. In this case, the balloon needs to have an additional option set, balloonPane:

Picture of the exampleExample
var myPlacemark = new ymaps.Placemark([55.76, 37.64], {
        balloonContent: 'I went off the map'
        }, {
        balloonPane: 'outerBalloon'
    });

See the Examples.

Saving the map state in a URL

A user who is working with the map often changes the map state: center, zoom, type, and so on. If the page is reloaded, these changes will be lost. One way to save the current map state is to use a URL hash.

In the example below, map parameters are passed to the URL hash when events occur that change the map state. When the page is reloaded, the map state is set according to the passed parameters.

Open example in a new window