@glook/react-yandex-maps

Yandex.Maps JS API 2.1 bindings for React, in TypeScript.

This is a maintained, TypeScript-first fork of react-yandex-maps 4.x. The public API is kept 1:1 with [email protected], so for most projects migrating is just changing the import. What changed under the hood: the source is TypeScript, the bundle ships ESM + CJS + generated types, runtime dependencies are gone, and React 17 / 18 / 19 are supported and tested in CI.

Install

npm install @glook/react-yandex-maps

react is a peer dependency (^17.0.2 || ^18 || ^19).

Quick start

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

export default function App() {
    return (
        <YMaps query={{apikey: 'YOUR_API_KEY'}}>
            <Map
                defaultState={{center: [55.75, 37.57], zoom: 9}}
                width="100%"
                height={400}
            >
                <Placemark defaultGeometry={[55.75, 37.57]} />
            </Map>
        </YMaps>
    );
}

An API key is optional for development (the map loads with a watermark), but get one for production use.

Migrating from react-yandex-maps

The component surface, props (state/defaultState, options/defaultOptions, onXxx events, instanceRef, withYMaps) and the exported type names are unchanged. In most cases the migration is a single find-and-replace:

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

Notable differences:

• TypeScript types are generated from the source and shipped in the package (no separate @types install, no hand-written typings/).
• propTypes were removed — validation now comes from TypeScript.
• No UMD build. Only ESM (import) and CJS (require) entry points are published; the old dev/prod dual bundle and the root index.js switcher are gone.

React compatibility

The class-component lifecycle the library is built on is immune to StrictMode's double-invoked effects, so the same code runs on every supported major.

| React | Status | | ----- | ------------------------- | | 17 | ✅ tested in CI (RTL 12) | | 18 | ✅ tested in CI | | 19 | ✅ tested in CI |

Documentation

Live component examples (Storybook): https://glook.github.io/react-yandex-maps/

Developing locally

npm install          # install dependencies
npm run typecheck    # tsc --noEmit
npm test             # jest (unit + React-rendered integration tests)
npm run build        # tsup -> dist (ESM + CJS + .d.ts)
npm run storybook    # live Storybook sandbox on http://localhost:6008

Set STORYBOOK_YMAPS_API_KEY to use your own API key in the Storybook sandbox.

License

MIT. Originally created by Sergey Petushkov; this fork is maintained by @glook.

Thanks to @effrenus and yandex-map-react for inspiring the original library.