Overview

Namespace

All API components belong to the ymaps3 namespace.

Component names

The name of any JS API component satisfies two conditions:

  • starts with a capital letter with the prefix YMap
  • written in CamelCase.

For example: YMap, YMapMarker, YMapListener.

Map objects

Name

Description

Representation in the API

Map

The main object that coordinates its components.

YMap class

Layer

An object for displaying data.

Classes with the Layer postfix

Data source

An object for loading data that transfers the display data to layers.

Classes with the DataSource postfix

Marker

A map element with the DOM content, wrapper over YMapFeature.

YMapMarker class

Geo object

A polygon, a line, a marker.

YMapFeature class

Visual elements

Objects used to manage the map: zoom button, geolocation button, and so on.

Classes with the Control postfix

Utilities

Auxiliary objects for working with the API. For example, YMapListener is responsible for subscribing to the map's events.

YMapListener class

Hierarchy of map objects

Some map objects (such as the map itself) may contain internal nodes known as children. Other objects (such as YMapTileDataSource) don't have this feature.

Map

YMap is the root element in the hierarchy. To initialize it, in the constructor of the object you need to pass:

<!-- Create a container for the map -->
<div id="root"></div>

const {YMap} = ymaps3;

// Initialize the map
const map = new YMap(

  // Pass the link to the HTMLElement of the container
  document.getElementById('root'),

  // Pass the map initialization parameters
  {
    location: {
      zoom: 10,
      center: [25.229762, 55.289311]
    }
  }
);

All JS API objects are initialized according to their own rules, but they are added to the map using the addChild() method called from the map instance. You can delete objects using the symmetric removeChild() method:

const {YMap, YMapLayer} = ymaps3;

// Initialize the map
const map = new YMap(...);

// Initialize the layer
const layer = new YMapLayer(...);

// Add this layer to the map
map.addChild(layer);

Learn more about YMap.

Layer

A layer is a visual component that is responsible for drawing some objects on the map. For example, the marker layer displays points on the map, and the tile layer displays the geographical map itself.

The map can contain any number of layers, the API has no restrictions on the number of layers. For example, you may add a layer on which images with clouds will be displayed, place a tile layer under it, and add a layer of traffic jams between them.

Alert

By default, the map displays layers in the order they were added.
You can also easily control this order using the zIndex parameter.

Learn more about YMapLayer.

Data sources

Each layer needs data to display. In the JS API, data sources are objects with the DataSource postfix. For example, YMapTileDataSource is an object for loading raster or vector map tiles.

For example, you want to display tiles received from the site https://sitename.com :

const {YMap, YMapTileDataSource, YMapLayer} = ymaps3;

// Initialize the map
const map = new YMap({...});

// Initialize the data source
const tileDataSource = new YMapTileDataSource({
  id: 'someSource',
  raster: {
    type: 'someType',
    fetchTile: 'https://sitename.com/?x={{x}}&y={{y}}&z={{z}}&scale={{scale}}'
  }
});

// Add the data source to the map
map.addChild(tileDataSource);

// Create a layer with the received data
const layer = new YMapLayer({
  zIndex: 1,
  source: 'someSource',
  type: 'someType'
});

// Add this layer to the map
map.addChild(layer);

Note

A text identifier is used to link the data source and the layer. Be careful, the identifier for the data source is set in the id field, and the source field is used when transferring to the layer.

Layer with data source

There are several layers in the JS API for which data sources are already configured.

  • YMapDefaultFeaturesLayer — adds a data source and a layer of geo objects (polygons, lines, points, placemarks)
  • YMapDefaultSchemeLayer — adds a data source and a schema layer
    • type: 'ground' — the entire schema in the raster version, the earth layer in the vector version
    • type: 'buildings' — a layer of buildings in the vector version
    • type: 'icons' — icon layer in the vector version
    • type: 'labels' — labels layer in the vector version

For example, this code will add all "schema" type layers with all data sources to the map:

map.addChild(new YMapDefaultSchemeLayer({theme: 'light'}));

Note

In this example, the layer constructor receives only the color theme as parameter, the other parameters are used by default from YMapDefaultSchemeLayer.defaultProps

You may manually do all the same things as in the example above:

// First add an invisible layer to the map.
// It is hidden because it is only used for loading data.
map.addChild(new YMapDefaultSchemeLayer({theme: 'light', visible: false, source: 'scheme'}));

// Then add several layers to the map, specifying for each of them
// which data from YMapDefaultSchemeLayer to display.
map.addChild(new YMapLayer({zIndex: 1, source: 'scheme', type: 'ground'}))
map.addChild(new YMapLayer({zIndex: 2, source: 'scheme', type: 'labels'}))
map.addChild(new YMapLayer({zIndex: 3, source: 'scheme', type: 'buildings'}))
map.addChild(new YMapLayer({zIndex: 4, source: 'scheme', type: 'icons'}))

Marker

Marker is DOM-element with reference to coordinates. Markers can be dragged and adjusted their appearance using the HTML.

const {YMap, YMapDefaultSchemeLayer, YMapDefaultFeaturesLayer, YMapMarker} = ymaps3;

// Initialize the map
const map = new YMap({...});

// Add a layer with roads and buildings
map.addChild(new YMapDefaultSchemeLayer());

// Add a layer for markers
map.addChild(new YMapDefaultFeaturesLayer());

// Create a DOM element for the marker content.
// It is important to do this before initializing the marker!
// The element can be created empty. You can add HTML markup inside after initializing the marker.
const content = document.createElement('section');

// Initialize the marker
const marker = new YMapMarker(
  {
    coordinates: [25.229762, 55.289311],
    draggable: true
  },
  content
);

// Add a marker to the map
map.addChild(marker);

// Add custom HTML markup inside the marker content
content.innerHTML = '<h1>You can drag this header</h1>';

Learn more about YMapMarker.

Initialization parameters

Parameters passed to objects during initialization can be mandatory and optional. For example, the YMap component has the location field required, but `behaviors is not.

const {YMap} = ymaps3;

const map = new YMap(document.getElementById('root'), {
  location: {
    zoom: 10,
    center: [25.229762, 55.289311]
  },
  behaviors: ['drag', 'scrollZoom', 'pinchZoom', 'dblClick']
});

Learn more about initialization parameters.

Strict mode

You can enable strict mode to track errors in the code. Use the global option strictMode:

ymaps3.strictMode = true;

In strict mode, the JS API checks the input data. For example, if you add an object to the map that is not a descendant of YMapEntity, the JS API will inform you about it. With strict mode turned off, the JS API will not do such a check, and your code may not work correctly.

Learn more about Strict mode.

React

There is a React analog for each object in the JS API. To use the React version of the API, connect the @yandex/ymaps3-reactify module:

const ymaps3Reactify = await ymaps3.import('@yandex/ymaps3-reactify');
const reactify = ymaps3Reactify.reactify.bindTo(React, ReactDOM);
const {YMap, YMapDefaultSchemeLayer, YMapDefaultFeaturesLayer, YMapMarker} = reactify.module(ymaps3);

Note

The @yandex/ymaps3-reactify module provides a set of methods for accessing React both individual objects and modules/packages as a whole. The hierarchy of objects and initialization parameters are the same.

After connecting the module, use any JS API objects as React components:

<YMap location={{center: [25.229762, 55.289311], zoom: 9}} mode="vector">
  <YMapDefaultSchemeLayer />
  <YMapDefaultFeaturesLayer />

  <YMapMarker coordinates={[25.229762, 55.289311]} draggable={true}>
    <section>
      <h1>You can drag this header</h1>
    </section>
  </YMapMarker>
</YMap>

Note

For more information about integration with React and other frameworks, see the section Integrations

Previous
Quick start
Next
Connecting the API
In this article: