@react-google-maps/api
v2.20.4
Published
React.js Google Maps API integration
Downloads
2,622,552
Keywords
Readme
@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
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 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 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
pnpm install @react-google-maps/api
with NPM
npm i -S @react-google-maps/api
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 ? (
<GoogleMap
mapContainerStyle={containerStyle}
center={center}
zoom={10}
onLoad={onLoad}
onUnmount={onUnmount}
>
{/* Child components, such as markers, info windows, etc. */}
<></>
</GoogleMap>
) : (
<></>
)
}
export default React.memo(MyComponent)
Migration from [email protected]
if you need an access to map object, instead of ref
prop, you need to use onLoad
callback on <GoogleMap />
component.
Before:
// before - don't do this!
<GoogleMap
ref={(map) => {
const bounds = new window.google.maps.LatLngBounds()
map.fitBounds(bounds)
}}
/>
After:
<GoogleMap
onLoad={(map) => {
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 <LoadScript />
. 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 - forbids loading of Roboto fonts, if you set property preventGoogleFonts on
<LoadScript preventGoogleFonts />
component
Examples
Examples can be found in two places:
- Official docs (powered by react-styleguidist.
- A Gatsby app including some examples. See the 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
Community Help Resource
You can join our Slack channel
Contribute
Maintainers and contributors are very welcome! See this issue 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!
- In the file
packages/react-google-maps-api/package.json
changemain
to"src/index.ts"
- In the same file, delete the
module
field - 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 [email protected] and later versions.