React Google Maps Component

2.2.5 · active · verified Sun Apr 19

google-map-react is an isomorphic React component that facilitates rendering custom React components directly onto a Google Map interface. Currently at version 2.2.5, the library maintains an active, though not rapid, release cadence, with recent updates ensuring compatibility with modern React versions, including React 19. Its primary differentiators include true isomorphic rendering capabilities, allowing server-side rendering for improved SEO, and the ability to render custom React components as markers or overlays on the map instead of relying solely on default Google Maps elements. Uniquely, it can calculate component positions on the map without immediate reliance on the full Google Maps API, which is loaded on demand only when the `GoogleMapReact` component is first used. This approach streamlines initial load times and provides a flexible way to integrate Google Maps into React applications.

Common errors

```
My map doesn't appear!
```
cause The HTML container element for the map has no defined width or height, causing the map to collapse to zero dimensions.

fix Apply explicit CSS `width` and `height` properties to the `div` element that wraps the `GoogleMapReact` component.
```
Google Maps JavaScript API error: InvalidKeyMapError
```
cause The API key provided in `bootstrapURLKeys` is either missing, invalid, incorrectly formatted, or does not have the Google Maps JavaScript API enabled, or billing is not set up on the associated Google Cloud project.

fix Verify your `key` in `bootstrapURLKeys` is correct. Check the Google Cloud Console to ensure the Maps JavaScript API is enabled for your project and that a billing account is linked.
```
Uncaught Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined. You likely forgot to export your component from the file it's defined in, or you might have mixed up default and named imports.
```
cause This generic React error can occur if a component intended to be rendered on the map (like a custom marker) is not correctly imported or exported, leading `GoogleMapReact` to receive an `undefined` element type.

fix Ensure all custom components passed as children to `GoogleMapReact` are correctly defined and exported, and imported with the correct syntax (e.g., `export default MyComponent;` for default imports, `export { MyComponent };` for named imports).

Warnings

breaking The import path for utility functions changed in v2.0.0. Instead of importing from `google-map-react/utils`, utilities are now exported directly from the main `google-map-react` module.
Fix: Change `import { utilName } from 'google-map-react/utils'` to `import { utilName } from 'google-map-react'`.
gotcha The map container element (`div` wrapping `GoogleMapReact`) must have explicitly defined `width` and `height` CSS properties. If not sized, the map will collapse and not appear.
Fix: Ensure the parent container of `GoogleMapReact` has explicit `height` and `width` styles (e.g., `height: '100vh', width: '100%'`).
gotcha To access the raw Google Maps `map` and `maps` objects via the `onGoogleApiLoaded` prop, you must explicitly set `yesIWantToUseGoogleMapApiInternals` to `true`.
Fix: Add the prop `yesIWantToUseGoogleMapApiInternals={true}` to your `GoogleMapReact` component when using `onGoogleApiLoaded`.
gotcha An invalid or missing `key` in `bootstrapURLKeys` will prevent the Google Map from loading correctly, often resulting in a grey map or console errors indicating an invalid API key.
Fix: Ensure `bootstrapURLKeys.key` is populated with a valid Google Maps API key that has the Maps JavaScript API enabled and billing configured in the Google Cloud Console.
deprecated Internal use of deprecated React lifecycle methods like `componentWillReceiveProps` were prefixed with `UNSAFE_` in v1.1.5. While fixed internally, users relying on older React component patterns might encounter related warnings if their own components use similar deprecated methods.
Fix: Migrate any custom React components interacting with the map to modern React lifecycle methods or hooks to avoid warnings in strict mode and future compatibility issues. Updates in 2.2.2 removed `findDOMNode` references, further modernizing the internal component structure.

Install

npm install google-map-react npm
yarn add google-map-react yarn
pnpm add google-map-react pnpm

Imports

GoogleMapReact
wrong:
```
const GoogleMapReact = require('google-map-react');
```
correct:
```
import GoogleMapReact from 'google-map-react';
```
The library primarily uses ESM imports. While CommonJS might technically work in some setups, the recommended and common practice is ESM `import`.
Utility functions
wrong:
```
import { someUtil } from 'google-map-react/utils';
```
correct:
```
import { someUtil } from 'google-map-react';
```
Since version 2.0.0, utility functions were moved from a submodule path (`/utils`) directly into the main module export.

Quickstart

This code demonstrates how to set up a basic Google Map with a custom React component serving as a marker. It highlights the explicit container sizing requirement and the API key configuration.

import React from 'react';
import GoogleMapReact from 'google-map-react';

const AnyReactComponent = ({ text }) => <div>{text}</div>;

export default function SimpleMap(){
  const defaultProps = {
    center: {
      lat: 10.99835602,
      lng: 77.01502627
    },
    zoom: 11
  };

  return (
    // Important! Always set the container height explicitly
    <div style={{ height: '100vh', width: '100%' }}>
      <GoogleMapReact
        bootstrapURLKeys={{ key: process.env.GOOGLE_MAPS_API_KEY ?? '' }}
        defaultCenter={defaultProps.center}
        defaultZoom={defaultProps.zoom}
      >
        <AnyReactComponent
          lat={59.955413}
          lng={30.337844}
          text="My Marker"
        />
      </GoogleMapReact>
    </div>
  );
}

view raw JSON →