# @react-google-maps/api
> React.js Google Maps API integration
Latest version **2.20.8** (published 2025-12-16) · MIT license · 0 weekly downloads
## Install
```sh
npm install @react-google-maps/api
pnpm add @react-google-maps/api
yarn add @react-google-maps/api
bun add @react-google-maps/api
```
## Health
**Score 60/100 (C)** — status: stable.
Positive: has types; esm support; no vulnerabilities; high quality score.
Warnings: low downloads.
## Facts
| | |
|---|---|
| Version | 2.20.8 |
| Published | 2025-12-16 |
| First published | 2019-01-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 6 |
| Unpacked size | 5.7 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1975 |
| Author | Alexey Lyakhov |
| Maintainers | justfly1984, uriklar_1 |
| Keywords | React, Google, Google Maps, google maps, google-maps, @google-maps, google-maps-api, @google-maps-api, Map, Maps, API, GoogleMap, react-component, addons/MarkerClusterer, directions/DirectionsRenderer, directions/DirectionsService, drawing/DrawingManager, places/SearchBox, InfoWindow, KmlLayer, Marker, MarkerClusterer, OverlayView, Circle, Polygon, Polyline, Rectangle, StreetViewPanorama, TrafficLayer, visualization/HeatmapLayer, ScriptLoader, Typescript |
## Links
- npm: https://www.npmjs.com/package/@react-google-maps/api
- Repository: https://github.com/JustFly1984/react-google-maps-api
- Homepage: https://react-google-maps-api-docs.netlify.app
- Issues: https://github.com/JustFly1984/react-google-maps-api/issues
- npm.io page: https://npm.io/package/@react-google-maps/api
## Dependencies (6)
- [invariant](https://npm.io/package/invariant.md) 2.2.4
- [@types/google.maps](https://npm.io/package/@types/google.maps.md) 3.58.1
- [@googlemaps/js-api-loader](https://npm.io/package/@googlemaps/js-api-loader.md) 1.16.8
- [@react-google-maps/infobox](https://npm.io/package/@react-google-maps/infobox.md) 2.20.0
- [@googlemaps/markerclusterer](https://npm.io/package/@googlemaps/markerclusterer.md) 2.5.3
- [@react-google-maps/marker-clusterer](https://npm.io/package/@react-google-maps/marker-clusterer.md) 2.20.0
## Alternatives
- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads
## Recent versions
- 2.20.8 (latest) — 2025-12-16
- 2.20.7 — 2025-06-18
- 2.20.6 — 2025-02-11
- 2.20.5 — 2024-12-24
- 2.20.4 — 2024-12-24
- 2.20.3 — 2024-10-11
- 2.20.2 — 2024-10-10
- 2.20.1 — 2024-10-10
- 2.20.0 — 2024-10-10
- 2.19.3 — 2024-02-11
- 2.19.2 — 2023-07-26
- 2.19.0 — 2023-07-15
- 2.18.1 — 2023-01-29
- 2.17.1 — 2022-12-08
- 2.17.0 — 2022-11-11
- … 129 more at https://npm.io/package/@react-google-maps/api/versions
## README
# @react-google-maps/api
[](https://www.npmjs.com/package/@react-google-maps/api)
[](https://www.npmjs.com/package/@react-google-maps/api)
[](https://www.npmjs.com/package/@react-google-maps/api)
@react-google-maps/api
You can donate or became a sponsor of the project here: [https://opencollective.com/react-google-maps-api#category-CONTRIBUTE](https://opencollective.com/react-google-maps-api#category-CONTRIBUTE)
> This library requires React v16.6 or later. To use the latest features (including hooks) requires React v16.8+. If you need support for earlier versions of React, you should check out [react-google-maps](https://github.com/tomchentw/react-google-maps)
> Versions starting 12.20.0 should support React@19.
This is complete re-write of the (sadly unmaintained) `react-google-maps` library. We thank [tomchentw](https://github.com/tomchentw/) for his great work that made possible.
@react-google-maps/api provides very simple bindings to the google maps api and lets you use it in your app as React components.
Here are the main additions to react-google-maps that were the motivation behind this re-write
## Install @react-google-maps/api
with PNPM
```shell
pnpm install @react-google-maps/api
```
with NPM
```shell
npm i -S @react-google-maps/api
```
```jsx
import React from 'react'
import { GoogleMap, useJsApiLoader } from '@react-google-maps/api'
const containerStyle = {
width: '400px',
height: '400px',
}
const center = {
lat: -3.745,
lng: -38.523,
}
function MyComponent() {
const { isLoaded } = useJsApiLoader({
id: 'google-map-script',
googleMapsApiKey: 'YOUR_API_KEY',
})
const [map, setMap] = React.useState(null)
const onLoad = React.useCallback(function callback(map) {
// This is just an example of getting and using the map instance!!! don't just blindly copy!
const bounds = new window.google.maps.LatLngBounds(center)
map.fitBounds(bounds)
setMap(map)
}, [])
const onUnmount = React.useCallback(function callback(map) {
setMap(null)
}, [])
return isLoaded ? (
{/* Child components, such as markers, info windows, etc. */}
<>
) : (
<>
)
}
export default React.memo(MyComponent)
```
## Migration from react-google-maps@9.4.5
if you need an access to map object, instead of `ref` prop, you need to use `onLoad` callback on `` component.
Before:
```jsx
// before - don't do this!
{
const bounds = new window.google.maps.LatLngBounds()
map.fitBounds(bounds)
}}
/>
```
After:
```jsx
{
const bounds = new window.google.maps.LatLngBounds()
map.fitBounds(bounds)
}}
onUnmount={(map) => {
// do your stuff before map is unmounted
}}
/>
```
If you want to use `window.google` object, you need to extract GoogleMap in separate module, so it is lazy executed then `google-maps-api` script is loaded and executed by ``. If you try to use `window.google` before it is loaded it will be undefined and you'll get a TypeError.
## Main features
- Simplified API
- Uses the new Context API
- Supports async React (StrictMode compliant)
- Removes lodash dependency =>
smaller bundle size `12.4kb` gzip, tree-shakeable [https://bundlephobia.com/result?p=@react-google-maps/api](https://bundlephobia.com/result?p=@react-google-maps/api)
- forbids loading of Roboto fonts, if you set property preventGoogleFonts on `` component
## Examples
Examples can be found in two places:
1. [Official docs](https://react-google-maps-api-docs.netlify.app/) (powered by [react-styleguidist](https://github.com/styleguidist/react-styleguidist).
2. A Gatsby app including some examples. See the [examples](https://github.com/JustFly1984/react-google-maps-api/tree/master/packages/react-google-maps-api-gatsby-example/src/examples) folder
## Advice
> Using the examples requires you to generate a google maps api key. For instructions on how to do that please see the following [guide](https://developers.google.com/maps/documentation/embed/get-api-key)
## Community Help Resource
You can join our [Slack channel](https://join.slack.com/t/react-google-maps-api/shared_invite/enQtODc5ODU1NTY5MzQ4LTBiNTYzZmY1YmVjYzJhZThkMGU0YzUwZjJkNGJmYjk4YjQyYjZhMDk2YThlZGEzNDc0M2RhNjBmMWE4ZTJiMjQ)
## Contribute
Maintainers and contributors are very welcome! See [this issue](https://github.com/JustFly1984/react-google-maps-api/issues/18) to get started.
## How to test changes locally
When working on a feature/fix, you're probably gonna want to test your changes. This workflow is a work in progress. Please feel free to improve it!
1. In the file `packages/react-google-maps-api/package.json` change `main` to `"src/index.ts"`
2. In the same file, delete the `module` field
3. You can now use the package `react-google-maps-api-gatsby-example` to test your changes. Just make sure you change the import from `@react-google-maps/api` to `../../../react-google-maps-api`
Since 1.2.0 you can use onLoad and onMount props for each @react-google-maps/api component, ref does not contain API methods anymore.
Since version 1.2.2 We added useGoogleMap hook, which is working only with React@16.8.1 and later versions.
---
_Source: https://npm.io/package/@react-google-maps/api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._