@yandex/ymaps3-hint

Yandex JS API Hints Package

The package adds the functionality of hanging hints on map elements

• Demo

How use

The package is located in the dist folder:

• dist/types TypeScript types
• dist/esm es6 modules for direct connection in your project
• dist/index.js Yandex JS Module

Recommended use @yandex/ymaps3-hint as usual npm package.

Usage with npm

Install @yandex/ymaps3-hint package from npm:

npm install @yandex/ymaps3-hint

The JS API is loaded dynamically, so the package must be used after the main JS API has loaded:

await ymaps3.ready; // waiting for the main JS API to load.

// ...

const {YMapHint} = await import('@yandex/ymaps3-hint');

// ...

map.addChild(new YMapHint(props));

You also need to import css styles into your project:

/* index.css */
@import '@yandex/ymaps3-hint/dist/esm/index.css';

Usage without npm

You can use CDN with module loading handler in JS API on your page.

By default ymaps3.import can load self modules. Just use ymaps3.registerCdn and ymaps3.import:

// register in `ymaps3.import` which CDN to take the package from
ymaps3.import.registerCdn('https://cdn.jsdelivr.net/npm/{package}', '@yandex/ymaps3-hint@latest');

// ...

// import package from CDN
const {YMapHint, YMapHintContext} = await ymaps3.import('@yandex/ymaps3-hint');

Working with the package

async function main() {
  const map = new ymaps3.YMap(document.getElementById('app'), {location: LOCATION});

  map.addChild(new ymaps3.YMapDefaultSchemeLayer());

  const defaultFeatures = new ymaps3.YMapDefaultFeaturesLayer();
  map.addChild(defaultFeatures);

  const hint = new YMapHint({
    layers: [defaultFeatures.layer],
    hint: (object) => object?.properties?.hint
  });

  map.addChild(hint);

  hint.addChild(
    new (class MyHint extends ymaps3.YMapEntity {
      _onAttach() {
        this._element = document.createElement('div');
        this._element.className = 'my-hint';

        this._detachDom = ymaps3.useDomContext(this, this._element);
        this._watchContext(
          YMapHintContext,
          () => {
            this._element.textContent = this._consumeContext(YMapHintContext)?.hint;
          },
          {immediate: true}
        );
      }

      _onDetach() {
        this._detachDom();
      }
    })()
  );

  map.addChild(new ymaps3.YMapMarker({coordinates: LOCATION.center, properties: {hint: 'Some hint'}}));
}
main();

React version

ReactDOM.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
  document.getElementById('app')
);

function App() {
  const [location, setLocation] = useState(LOCATION);

  const getHint = useCallback((object) => object && object.properties && object.properties.hint, []);

  return (
    <YMap location={location} ref={(x) => (map = x)}>
      <YMapDefaultSchemeLayer />
      <YMapDefaultFeaturesLayer />
      <YMapControls position="right">
        <YMapZoomControl />
      </YMapControls>

      <YMapHint hint={getHint}>
        <MyHint />
      </YMapHint>

      <MyMarker coordinates={LOCATION.center} properties={{hint: 'Some text'}} color={'#ff00ff'} />
    </YMap>
  );
}
function MyMarker({coordinates, properties, color}) {
  return (
    <YMapMarker properties={properties} coordinates={coordinates}>
      <div
        dangerouslySetInnerHTML={{__html: '<svg>...</svg>'}}
        style={{transform: 'translate(-15px, -33px)', position: 'absolute'}}
      ></div>
    </YMapMarker>
  );
}
function MyHint() {
  const ctx = React.useContext(YMapHintContext);
  return <div className="my-hint">{ctx && ctx.hint}</div>;
}