README.md

ymap3-components

Library to get components of ymaps3 via import

This library is an alternative way of getting Yandex map components: use import instead of creating script and getting components via asynchronous window.ymaps3.import

Library is written on typescript with @yandex/ymaps3-types.

Install Library

npm i ymap3-components

Usage with typescript

npm i -D @yandex/ymaps3-types@latest

Examples

• See primary example in codesandbox
• Here is an example with clusterer

Motivation

• keeps your components simple
• this is easier than suggestions in Official documentation
• no need to write logic of loading components and modules for them
• no need to create script or configure externals in webpack

✅ Your code with this library

import React from "react";
import {
  YMap,
  YMapDefaultSchemeLayer,
  YMapDefaultFeaturesLayer
  // ...other components
} from "ymap3-components";
import { features, LOCATION } from './helpers'

function Map() {
  return (
    <YMapComponentsProvider apiKey={process.env.REACT_APP_YMAP_KEY}>
      <YMap location={location}>
        <YMapDefaultSchemeLayer />
        <YMapDefaultFeaturesLayer />
        <YMapDefaultMarker
          coordinates={LOCATION.coordinates}
        />
      </YMap>
    </YMapComponentsProvider>
  );
}

export default Map;

❌ Your code without this library

import React, {useEffect, useMemo} from "react";
import {features, LOCATION} from './helpers'

function Map() {
  const [data, setData] = useState(); 
  const {
    YMap,
    // ...other components
  } = useMemo(() => {
    if (data?.reactify) {
      return reactify.module(data.ymap);
    }
  }, [data]);

  useEffect(() => {
    const script = document.createElement('script');
    document.body.appendChild(script);
    script.type = "text/javascript";
    script.src = `https://api-maps.yandex.ru/v3/?apikey=${key}&lang=${lang}`;
    script.onload = async () => {
      const ymaps = window.ymaps3
      await ymaps.ready;
      const ymaps3Reactify = await ymaps.import('@yandex/ymaps3-reactify');
      const reactify = ymaps3Reactify.reactify.bindTo(React, ReactDOM);

      setData({
        reactify,
        ymaps
      });
      /*
      and other logic which is not connected with rendering
      to load ymap modules like YMapDefaultMarker
      */
    }
  }, [])
  
  if (!YMap) {
    return null;
  }

  return (
    <YMap location={location}>
      <YMapDefaultSchemeLayer/>
      <YMapDefaultFeaturesLayer/>
      <YMapDefaultMarker
        coordinates={LOCATION.coordinates}
      />
    </YMap>
  );
}

export default Map;

Getting Stated

1. Get api key for map js api
2. Set domain where you will host ymap
3. For development change your /etc/host to proxy domain on your localhost (map will work on http://{domain}:{port})
4. Install and use library

Check example in codesandbox below. For more comprehensive information go to Official documentation

API

YMapComponentsProvider API

YMapComponentsProvider - root component which has to contain another library's components as child nodes.

interface YMapComponentsProviderProps {
  apiKey: string
  lang?: string
  onLoad?: (params: {
    reactify: Reactify;
    ymaps: typeof import("@yandex/ymaps3-types/index");
  }) => any
  onError: (e?: unknown) => void
  children: ReactNode | ReactNode []
}

Other components has same api as provided in Official documentation

Library provides api for these components:

• YMapComponentsProvider
• YMap
• YMapDefaultMarker
• YMapHintContext
• YMapHint
• YMapClusterer
• YMapZoomControl
• YMapGeolocationControl
• ThemeContext
• YMapDefaultSchemeLayer
• YMapDefaultFeaturesLayer
• YMapLayer
• YMapControl
• YMapControls
• YMapControlButton
• YMapTileDataSource
• YMapMarker
• YMapListener
• YMapFeature
• YMapDefaultSatelliteLayer
• YMapCollection
• YMapContainer
• YMapFeatureDataSource
• YMapCustomClusterer