Skip to main content

Getting Started

@pbe/react-yandex-maps is a wrapper around Yandex.Maps API that allows you to render Yandex Maps in your React application with minimum amount of hassle 🎉

Installation​

Use npm/yarn to install the library from npm registry:

With npm:

npm install --save @pbe/react-yandex-maps

With yarn:

yarn add @pbe/react-yandex-maps

Adding Maps to Your Application​

Adding maps to your application can be splitted in two steps.

First, we will add provider component, that will handle loading the Yandex.Maps API and providing it to any interested component on the page. Usually you don't want to have several providers on one page. A good place to put your provider could the at the top of your application:

import { YMaps } from '@pbe/react-yandex-maps';

const App = () => (
  <YMaps>
    <div>My awesome application with maps!</div>
  </YMaps>
);

Then add the Map component with desired state somewhere on the page:

import { YMaps, Map } from '@pbe/react-yandex-maps';

const App = () => (
  <YMaps>
    <div>
      My awesome application with maps!
      <Map defaultState={{ center: [55.75, 37.57], zoom: 9 }} />
    </div>
  </YMaps>
);

That's it! Now, as soon as Yandex.Maps API is loaded by YMaps provider component, Map component will render ymaps.Map object on the page.

Before you start playing around with the library I higly recommend taking a quick look at the "What is supported?" section and a more thorough look at "Basic Principles" section

What Is Supported?​

This library is a thin wrapper over Yandex.Maps API, a lot of Yandex.Maps API objects and features are supported with React components but not all of them and not all of their features.

Here is a list of supported features and objects:

Supported Features​

  • Modifying Yandex.Maps API request via YMaps provider component
  • Getting access to Yandex.Maps API in your components via withYMaps HOC
  • Granular load of the required API modules with Yandex.Maps modules API
  • Controlled and uncontrolled components for every supported object
  • Enterprise API via YMaps query prop

Controlled props that are mentioned above are not 100% controlled as there is no way to stop Yandex. Map objects from updating completely with the library API. When using controlled props, you should keep in mind that your state/properties/options and Yandex.Maps object state/properties/options could go out of sync.

Supported Yandex. Map Objects​

Map, Panorama

Supported GeoObjects​

GeoObject, Placemark, Polyline, Rectangle, Polygon, Circle, Clusterer, ObjectManager

Supported Controls​

Button, FullscreenControl, GeolocationControl, ListBox, ListBoxItem, RouteButton, RouteEditor, RoutePanel, RulerControl, SearchControl, TrafficControl, TypeSelector, ZoomControl

What Is Not Supported?​

Rendering React DOM nodes to the Yandex.Maps template factories is not supported (i.e., you can't render balloon content with React with this library out of the box), see FAQ for more info.

Core Principles​

There are a few core principles that are forming the base of this library. It will be very helpful to keep those in mind, when you are using it.